From: Zbigniew Jędrzejewski-Szmek Date: Fri, 7 Mar 2014 04:24:20 +0000 (-0500) Subject: man: describe functions for appending to messages X-Git-Tag: v211~77 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22;ds=sidebyside man: describe functions for appending to messages --- diff --git a/Makefile-man.am b/Makefile-man.am index 40810e3f0..c232f486d 100644 --- a/Makefile-man.am +++ b/Makefile-man.am @@ -688,6 +688,11 @@ MANPAGES += \ man/sd_bus_creds_new_from_pid.3 \ man/sd_bus_error.3 \ man/sd_bus_label_escape.3 \ + man/sd_bus_message_append.3 \ + man/sd_bus_message_append_array.3 \ + man/sd_bus_message_append_basic.3 \ + man/sd_bus_message_append_string_memfd.3 \ + man/sd_bus_message_append_strv.3 \ man/sd_bus_message_get_cookie.3 \ man/sd_bus_message_get_monotonic_usec.3 \ man/sd_bus_new.3 \ @@ -734,6 +739,11 @@ MANPAGES_ALIAS += \ man/sd_bus_error_set_errno.3 \ man/sd_bus_error_set_errnof.3 \ man/sd_bus_label_unescape.3 \ + man/sd_bus_message_append_array_iovec.3 \ + man/sd_bus_message_append_array_memfd.3 \ + man/sd_bus_message_append_array_space.3 \ + man/sd_bus_message_append_string_iovec.3 \ + man/sd_bus_message_append_string_space.3 \ man/sd_bus_message_get_realtime_usec.3 \ man/sd_bus_message_get_reply_cookie.3 \ man/sd_bus_message_get_seqnum.3 \ @@ -782,6 +792,11 @@ man/sd_bus_error_set_const.3: man/sd_bus_error.3 man/sd_bus_error_set_errno.3: man/sd_bus_error.3 man/sd_bus_error_set_errnof.3: man/sd_bus_error.3 man/sd_bus_label_unescape.3: man/sd_bus_label_escape.3 +man/sd_bus_message_append_array_iovec.3: man/sd_bus_message_append_array.3 +man/sd_bus_message_append_array_memfd.3: man/sd_bus_message_append_array.3 +man/sd_bus_message_append_array_space.3: man/sd_bus_message_append_array.3 +man/sd_bus_message_append_string_iovec.3: man/sd_bus_message_append_string_memfd.3 +man/sd_bus_message_append_string_space.3: man/sd_bus_message_append_string_memfd.3 man/sd_bus_message_get_realtime_usec.3: man/sd_bus_message_get_monotonic_usec.3 man/sd_bus_message_get_reply_cookie.3: man/sd_bus_message_get_cookie.3 man/sd_bus_message_get_seqnum.3: man/sd_bus_message_get_monotonic_usec.3 @@ -906,6 +921,21 @@ man/sd_bus_error_set_errnof.html: man/sd_bus_error.html man/sd_bus_label_unescape.html: man/sd_bus_label_escape.html $(html-alias) +man/sd_bus_message_append_array_iovec.html: man/sd_bus_message_append_array.html + $(html-alias) + +man/sd_bus_message_append_array_memfd.html: man/sd_bus_message_append_array.html + $(html-alias) + +man/sd_bus_message_append_array_space.html: man/sd_bus_message_append_array.html + $(html-alias) + +man/sd_bus_message_append_string_iovec.html: man/sd_bus_message_append_string_memfd.html + $(html-alias) + +man/sd_bus_message_append_string_space.html: man/sd_bus_message_append_string_memfd.html + $(html-alias) + man/sd_bus_message_get_realtime_usec.html: man/sd_bus_message_get_monotonic_usec.html $(html-alias) @@ -1355,6 +1385,11 @@ EXTRA_DIST += \ man/sd_bus_creds_new_from_pid.xml \ man/sd_bus_error.xml \ man/sd_bus_label_escape.xml \ + man/sd_bus_message_append.xml \ + man/sd_bus_message_append_array.xml \ + man/sd_bus_message_append_basic.xml \ + man/sd_bus_message_append_string_memfd.xml \ + man/sd_bus_message_append_strv.xml \ man/sd_bus_message_get_cookie.xml \ man/sd_bus_message_get_monotonic_usec.xml \ man/sd_bus_new.xml \ diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml new file mode 100644 index 000000000..2a1e95aa3 --- /dev/null +++ b/man/sd_bus_message_append.xml @@ -0,0 +1,254 @@ + + + + + + + + + sd_bus_message_append + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append + 3 + + + + sd_bus_message_append + + Attach parts of message based on a format string + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append + sd_bus_message *m + const char *types + ... + + + + + + Description + + Function sd_bus_message_append appends + a sequence of items to message m. The + format string types describes the types of + arguments that follow. + + The format 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, a + variant type code, an array with its element type, or a dictionary + with its entry type. The format string is + NUL-terminated. + + 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 variant is denoted by v. Correspoding + arguments must include a format 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 include the size of + the array, and then repeated this number of times, arguments + corresponding to the nested type. + + 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 include + the size of the dictionary, and then repeated this number of + times, arguments corresponding to each of the two nested + types. + + + Item format specifiers + + + + + + + + + + a + SD_BUS_TYPE_ARRAY + array + determined by array type and size + + + + v + SD_BUS_TYPE_VARIANT + variant + determined by the type argument + + + + ( + SD_BUS_TYPE_STRUCT_BEGIN + array start + determined by the nested types + + + ) + SD_BUS_TYPE_STRUCT_END + array end + + + + { + SD_BUS_TYPE_DICT_ENTRY_BEGIN + dictionary entry start + determined by the nested types + + + } + SD_BUS_TYPE_DICT_ENTRY_END + dictionary entry end + + + +
+ + + + Types string grammar + + types ::= complete_type* +complete_type ::= basic_type | variant | structure | array | dictionary +basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" | + "b" | "h" | + "s" | "o" | "g" +variant ::= "v" +structure ::= "(" complete_type+ ")" +array ::= "a" complete_type +dictionary ::= "a" "{" basic_type complete_type "}" + + + + + Examples + + Append a single basic type (the string a string): + + + sd_bus_message *m; +... +sd_bus_message_append(m, "s", "a string"); + + Append all types of integers: + + uint8_t y = 1; +int16_t n = 2; +uint16_t q = 3; +int32_t i = 4; +uint32_t u = 5; +int32_t x = 6; +uint32_t t = 7; +double d = 8.0; +sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d); + + Append a structure composed of 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": + + sd_bus_message_append(m, "v", "g", "sdbusisgood"); + + Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}: + + + sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL); + + + + + Return Value + + On success, this call returns 0 or a positive + integer. On failure, this call returns a negative + errno-style error code. + + + + + + Notes + + sd_bus_open_user() and other functions + described here are available as a shared library, which can be + compiled and linked to with the + libsystemd-bus pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_new3, + sd_bus_ref3, + sd_bus_unref3, + ssh1, + systemd-machined.service8, + machinectl1 + + + + diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml new file mode 100644 index 000000000..fe84671f3 --- /dev/null +++ b/man/sd_bus_message_append_array.xml @@ -0,0 +1,190 @@ + + + + + + + + + sd_bus_message_append_array + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_array + 3 + + + + sd_bus_message_append_array + sd_bus_message_append_array_memfd + sd_bus_message_append_array_iovec + sd_bus_message_append_array_space + + Attach an array of items to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_array + sd_bus_message *m + char type + char void *ptr + size_t size + + + + int sd_bus_message_append_array_memfd + sd_bus_message *m + char type + sd_memfd *memfd + + + + int sd_bus_message_append_array_iovec + sd_bus_message *m + char type + const struct iovec *iov + unsigned n + + + + int sd_bus_message_append_array_space + char type + size_t size + char void **ptr + + + + + + Description + + Function sd_bus_message_append_array + appends items to message m as the single + array. A container will be opened, items appended, and the + container closed. Parameter type determines + how pointer p is interpreted. + type must be one of the "trivial" types + y, n, q, + i, u, x, + t, d (but not + b), as defined by the + Basic Types + section of the D-Bus specification, and listed in + sd_bus_message_append_basic3. + Pointer p must point to an array of of size + size bytes containing items of the + respective type. Size size must be a + multiple of the size of the type type. As a + special case, p may be + NULL, if size is 0. + + + The memory pointed at by p is copied + into the memory area containing the message and may be changed + after this call. + + Function + sd_bus_message_append_array_memfd appends + items to message m, similarly to + sd_bus_message_append_array. Contents of the + memory file descriptor memfd are used as + the contents of the array. Their size must be a multiple of the + size of the type type. + + Descriptor memfd will be sealed + and cannot be modified after this call. + + Function + sd_bus_message_append_array_iovec appends + items to message m, similarly to + sd_bus_message_append_array. Contents of the + iovec iov are used as the contents of the + array. The total size of iov payload (the + sum of iov_len fields) must be a multiple + of the size of the type type. + + Pointer iov must point to + n struct iovec + structures. Each structure may have the + iov_base field set, in which case the + memory pointed to will be copied into the message, or unset, in + which case a block of zeros of length + iov_len bytes will be inserted. The + memory pointed at by iov may be changed + after this call. + + Function + sd_bus_message_append_array_space appends + space for an array of items to message m. + It behaves the same as + sd_bus_message_append_array, but instead + of copying items to the message, it returns a pointer to the + destination area to the caller in pointer p. + + + + + Return Value + + On success, those calls return 0 or a positive integer. On + failure, they returns a negative errno-style error code. + + + + + + Notes + + sd_bus_append_array() and other + functions described here are available as a shared library, which + can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_append_basic3, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_append_basic.xml b/man/sd_bus_message_append_basic.xml new file mode 100644 index 000000000..a8e91f9e9 --- /dev/null +++ b/man/sd_bus_message_append_basic.xml @@ -0,0 +1,278 @@ + + + + + + + + + sd_bus_message_append_basic + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_basic + 3 + + + + sd_bus_message_append_basic + + Attach a single part to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_basic + sd_bus_message *m + char type + char void *p + + + + + + Description + + sd_bus_message_append_basic appends a + single item to the message m. Parameter + type determines how pointer + p is interpreted. + type must be one of the basic types + as defined by the + + Basic Types + section of the D-Bus specification, and listed in the table below. + + + + Item format specifiers + + + + + + + + + Specifier + Constant + Description + Size + + + + + y + SD_BUS_TYPE_BYTE + unsigned interger + 1 byte + + + + b + SD_BUS_TYPE_BOOLEAN + boolean + 4 bytes + + + + n + SD_BUS_TYPE_INT16 + signed integer + 2 bytes + + + + q + SD_BUS_TYPE_UINT16 + unsigned integer + 2 bytes + + + + i + SD_BUS_TYPE_INT32 + signed integer + 4 bytes + + + + u + SD_BUS_TYPE_UINT32 + unsigned integer + 4 bytes + + + + x + SD_BUS_TYPE_INT64 + signed integer + 8 bytes + + + + t + SD_BUS_TYPE_UINT64 + unsigned integer + 8 bytes + + + + d + SD_BUS_TYPE_DOUBLE + floating-point + 8 bytes + + + + s + SD_BUS_TYPE_STRING + Unicode string + variable + + + + o + SD_BUS_TYPE_OBJECT_PATH + object path + variable + + + + g + SD_BUS_TYPE_SIGNATURE + signature + variable + + + + h + SD_BUS_TYPE_UNIX_FD + UNIX file descriptor + 4 bytes + + + +
+ + The value of the parameter is copied into the memory area + containing the message and may be changed after this call. If + type is h (UNIX file + descriptor), it is always "consumed" by this call, and either + successfully appended to the message or closed. + + For types s, o, and + g, the parameter p is + interpreted as a pointer to a NUL-terminated + character sequence. As a special case, a NULL + pointer is interpreted as an empty string. The string should be + valid Unicode string encoded as UTF-8. In case of the two latter + types, additionally the requirements for a D-Bus object path or + type signature should be satisfied. Those requirements should be + verified by the recepient of the message. + + + + + Return Value + + On success, this call returns 0 or a positive integer. On + failure, it returns a negative errno-style error code. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + Specified parameter is invalid. + + + + + -EPERM + + Message has been sealed. + + + + + -ESTALE + + Message is in invalid state. + + + + + -ENXIO + + Message cannot be appended to. + + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + sd_bus_append_basic() function + described here is available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_append_string_memfd.xml b/man/sd_bus_message_append_string_memfd.xml new file mode 100644 index 000000000..a9b892480 --- /dev/null +++ b/man/sd_bus_message_append_string_memfd.xml @@ -0,0 +1,153 @@ + + + + + + + + + sd_bus_message_append_string_memfd + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_string_memfd + 3 + + + + sd_bus_message_append_string_memfd + sd_bus_message_append_string_iovec + sd_bus_message_append_string_space + + Attach a string to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_string_memfd + sd_bus_message *m + sd_memfd *memfd + + + + int sd_bus_message_append_string_iovec + sd_bus_message *m + const struct iovec *iov + unsigned n + + + + int sd_bus_message_append_string_space + sd_bus_message *m + size_t size + char **s + + + + + + Description + + Functions + sd_bus_message_append_string_memfd and + sd_bus_message_append_string_iovec can be + used to append a single string (item of type s) + to message m. + + In case of + sd_bus_message_append_string_memfd the + contents of memfd are the string. They must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + In case of + sd_bus_message_append_string_iovec the + payload of iov is the string. It must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + Pointer iov must point to + n struct iovec + structures. Each structure may have the + iov_base field set, in which case the + memory pointed to will be copied into the message, or unset, in + which case a block of spaces (ASCII 32) of length + iov_len will be inserted. The + memory pointed at by iov may be changed + after this call. + + Function + sd_bus_message_append_string_space appends + space for a string to message m. If behaves + similarly to sd_bus_message_append_basic with + type s, but instead of copying a string into + the the message, it returns a pointer to the destination area to + the caller in pointer p. Space for string + of length size plus the terminating + NUL is allocated. + + + + Return Value + + On success, those calls return 0 or a positive integer. On + failure, they returns a negative errno-style error code. + + + + + + Notes + + Functions described here are available as a shared library, + which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append_basic3, + The D-Bus specification + + + + diff --git a/man/sd_bus_message_append_strv.xml b/man/sd_bus_message_append_strv.xml new file mode 100644 index 000000000..048bbcac0 --- /dev/null +++ b/man/sd_bus_message_append_strv.xml @@ -0,0 +1,116 @@ + + + + + + + + + sd_bus_message_append_strv + systemd + + + + A monkey with a typewriter + Zbigniew + Jędrzejewski-Szmek + zbyszek@in.waw.pl + + + + + + sd_bus_message_append_strv + 3 + + + + sd_bus_message_append_strv + + Attach an array of strings to a message + + + + + #include <systemd/sd-bus.h> + + + int sd_bus_message_append_strv + sd_bus_message *m + char **l + + + + + + Description + + Function sd_bus_message_append can be + used to append an array of strings to message + m. Parameter l + points to a NULL-terminated array of pointers + to NUL-terminated strings. Each string must + satisfy the same constraints as described for the + s type in + sd_bus_message_append_basic3. + + + The memory pointed at by p and the + contents of the strings themselves are copied into the memory area + containing the message and may be changed after this call. Note + that the signature of l parameter is be + treated as const char* const*, and the the contents + will not be modified. + + + + Return Value + + On success, this call returns 0 or a positive integer. On + failure, a negative errno-style error code is returned. + + + + + + Notes + + sd_bus_append_append_strv() function + described here is available as a shared library, which can be + compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_message_append3, + sd_bus_message_append_array3, + The D-Bus specification + + + + diff --git a/src/libsystemd/sd-bus/test-bus-marshal.c b/src/libsystemd/sd-bus/test-bus-marshal.c index 85aaf95d6..d438a231a 100644 --- a/src/libsystemd/sd-bus/test-bus-marshal.c +++ b/src/libsystemd/sd-bus/test-bus-marshal.c @@ -79,6 +79,9 @@ int main(int argc, char *argv[]) { r = sd_bus_message_new_method_call(NULL, &m, "foobar.waldo", "/", "foobar.waldo", "Piep"); assert_se(r >= 0); + r = sd_bus_message_append(m, ""); + assert_se(r >= 0); + r = sd_bus_message_append(m, "s", "a string"); assert_se(r >= 0);