From 60ef0942976adaebb935a48ecbcace3b58e57a76 Mon Sep 17 00:00:00 2001 From: Daan De Meyer Date: Thu, 19 Mar 2020 19:52:54 +0100 Subject: [PATCH] sd-bus: Add sd_bus_reply_method_return docs + cleanups --- man/rules/meson.build | 1 + man/sd-bus.xml | 1 + man/sd_bus_message_append.xml | 99 +++++++++++-------------- man/sd_bus_reply_method_error.xml | 26 +++---- man/sd_bus_reply_method_return.xml | 113 +++++++++++++++++++++++++++++ 5 files changed, 171 insertions(+), 69 deletions(-) create mode 100644 man/sd_bus_reply_method_return.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 21c92a3f12..84a8d6259e 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -325,6 +325,7 @@ manpages = [ 'sd_bus_reply_method_errnof', 'sd_bus_reply_method_errorf'], ''], + ['sd_bus_reply_method_return', '3', [], ''], ['sd_bus_request_name', '3', ['sd_bus_release_name', diff --git a/man/sd-bus.xml b/man/sd-bus.xml index 4232dcbe50..9e13af2cc9 100644 --- a/man/sd-bus.xml +++ b/man/sd-bus.xml @@ -86,6 +86,7 @@ sd_bus_new3, sd_bus_path_encode3, sd_bus_process3, +sd_bus_reply_method_return3, sd_bus_reply_method_error3, sd_bus_request_name3, sd_bus_set_address3, diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index b87468e373..a67819e0d7 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -20,8 +20,7 @@ sd_bus_message_append sd_bus_message_appendv - Attach fields to a D-Bus message based on a type - string + Attach fields to a D-Bus message based on a type string @@ -36,10 +35,10 @@ - int sd_bus_message_appendv - sd_bus_message *m - const char *types - va_list ap + int sd_bus_message_appendv + sd_bus_message *m + const char *types + va_list ap @@ -48,60 +47,49 @@ Description - The sd_bus_message_append() function - appends a sequence of fields to the D-Bus message object - m. The type string - types describes the types of the field - arguments that follow. For each type specified in the type string, - one or more arguments need to be specified, in the same order as - declared in the type string. + The sd_bus_message_append() function appends a sequence of fields to + the D-Bus message object m. The type string types + describes the types of the field arguments that follow. For each type specified in the type + string, one or more arguments need to be specified, in the same order as declared in the type + string. - The type string is composed of the elements shown in the - table below. It contains zero or more single "complete types". - Each complete type may be one of the basic types or a fully - described container type. A container type may be a structure with - the contained types, a variant, an array with its element type, or - a dictionary entry with the contained types. The type string is - NUL-terminated. + The type string is composed of the elements shown in the table below. It contains zero or + more single "complete types". Each complete type may be one of the basic types or a fully + described container type. A container type may be a structure with the contained types, a + variant, an array with its element type, or a dictionary entry with the contained types. The + type string is NUL-terminated. - In case of a basic type, one argument of the corresponding - type is expected. + In case of a basic type, one argument of the corresponding type is expected. - A structure is denoted by a sequence of complete types - between ( and ). This - sequence cannot be empty — it must contain at least one type. - Arguments corresponding to this nested sequence follow the same - rules as if they were not nested. + A structure is denoted by a sequence of complete types between ( and + ). This sequence cannot be empty — it must contain at least one type. + Arguments corresponding to this nested sequence follow the same rules as if they were not + nested. - A variant is denoted by v. Corresponding - arguments must begin with a type string denoting a complete type, - and following that, arguments corresponding to the specified type. - + A variant is denoted by v. Corresponding arguments must begin with a + type string denoting a complete type, and following that, arguments corresponding to the + specified type. - An array is denoted by a followed by a - complete type. Corresponding arguments must begin with the number of - entries in the array, followed by the entries themselves, - matching the element type of the array. + An array is denoted by a followed by a complete type. Corresponding + arguments must begin with the number of entries in the array, followed by the entries + themselves, matching the element type of the array. - A dictionary is an array of dictionary entries, denoted by - a followed by a pair of complete types between - { and }. The first of those - types must be a basic type. Corresponding arguments must begin - with the number of dictionary entries, followed by a pair of - values for each entry matching the element type of - the dictionary entries. + A dictionary is an array of dictionary entries, denoted by a followed + by a pair of complete types between { and }. The first of + those types must be a basic type. Corresponding arguments must begin with the number of + dictionary entries, followed by a pair of values for each entry matching the element type of the + dictionary entries. The sd_bus_message_appendv() is equivalent to the - sd_bus_message_append(), except that it is called with - a va_list instead of a variable number of arguments. This - function does not call the va_end() macro. Because it - invokes the va_arg() macro, the value of - ap is undefined after the call. + sd_bus_message_append(), except that it is called with a + va_list instead of a variable number of arguments. This function does not + call the va_end() macro. Because it invokes the + va_arg() macro, the value of ap is undefined after + the call. - For further details on the D-Bus type system, please consult - the D-Bus - Specification. + For further details on the D-Bus type system, please consult the + D-Bus Specification. + Item type specifiers @@ -162,7 +150,6 @@ NULL, which is equivalent to an empty string. See sd_bus_message_append_basic3 for the precise interpretation of those and other types. - @@ -205,12 +192,12 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); Append a structure composed of a string and a D-Bus path: sd_bus_message_append(m, "(so)", "a string", "/a/path"); - + Append an array of UNIX file descriptors: sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO); - + Append a variant, with the real type "g" (signature), and value "sdbusisgood": @@ -227,8 +214,8 @@ sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); Return Value - On success, these functions return 0 or a positive integer. On failure, they return a negative - errno-style error code. + On success, these functions return a non-negative integer. On failure, they return a + negative errno-style error code. diff --git a/man/sd_bus_reply_method_error.xml b/man/sd_bus_reply_method_error.xml index 5a6cef6bad..a1062ce2a9 100644 --- a/man/sd_bus_reply_method_error.xml +++ b/man/sd_bus_reply_method_error.xml @@ -22,7 +22,7 @@ sd_bus_reply_method_errno sd_bus_reply_method_errnof - Reply with an error to a method call + Reply with an error to a D-Bus method call @@ -63,12 +63,12 @@ Description - The sd_bus_reply_method_error() function sends an - error reply to the call message. The error structure - e specifies the error to send, and is used as described in + The sd_bus_reply_method_error() function sends an error reply to the + call message. The error structure e specifies the + error to send, and is used as described in sd_bus_message_new_error3. - If no reply is expected to call, this function returns - success without sending reply. + If no reply is expected to call, this function succeeds without sending a + reply. The sd_bus_reply_method_errorf() is to sd_bus_reply_method_error() what @@ -89,8 +89,9 @@ Return Value - These functions return 0 if the error reply was successfully sent or if - none was expected, and a negative errno-style error code otherwise. + This function returns a non-negative integer if the error reply was successfully sent or + if call does not expect a reply. On failure, it returns a negative + errno-style error code. Errors @@ -101,15 +102,14 @@ -EINVAL - The call message call is + The input parameter call is NULL. - Message call is not a method call message. - + Message call is not a method call message. Message call is not attached to a bus. - The error error parameter to + The error parameter error to sd_bus_reply_method_error is not set, see sd_bus_error_is_set3. @@ -137,7 +137,7 @@ - In addition, any error message returned by + In addition, any error returned by sd_bus_send1 may be returned. diff --git a/man/sd_bus_reply_method_return.xml b/man/sd_bus_reply_method_return.xml new file mode 100644 index 0000000000..8669730d0f --- /dev/null +++ b/man/sd_bus_reply_method_return.xml @@ -0,0 +1,113 @@ + + + + + + + + sd_bus_reply_method_return + systemd + + + + sd_bus_reply_method_return + 3 + + + + sd_bus_reply_method_return + + Reply to a D-Bus method call + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_reply_method_return + sd_bus_message *call + const char *types + ... + + + + + + Description + + sd_bus_reply_method_return() sends a reply to the + call message. The type string types and the + arguments that follow it must adhere to the format described in + sd_bus_message_append3. + If no reply is expected to call, this function succeeds without sending a + reply. + + + + Return Value + + On success, this function returns a non-negative integer. On failure, it returns a + negative errno-style error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -EINVAL + + The input parameter call is + NULL. + + Message call is not a method call message. + + + Message call is not attached to a bus. + + + + + -EPERM + + Message call has been sealed. + + + + + -ENOTCONN + + The bus to which message call is attached is not + connected. + + + + -ENOMEM + + Memory allocation failed. + + + + In addition, any error returned by + sd_bus_send1 + may be returned. + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_new_method_return3 + + + +