From effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Thu, 6 Mar 2014 23:24:20 -0500 Subject: man: describe functions for appending to messages --- man/sd_bus_message_append.xml | 254 ++++++++++++++++++++++++++ man/sd_bus_message_append_array.xml | 190 ++++++++++++++++++++ man/sd_bus_message_append_basic.xml | 278 +++++++++++++++++++++++++++++ man/sd_bus_message_append_string_memfd.xml | 153 ++++++++++++++++ man/sd_bus_message_append_strv.xml | 116 ++++++++++++ 5 files changed, 991 insertions(+) create mode 100644 man/sd_bus_message_append.xml create mode 100644 man/sd_bus_message_append_array.xml create mode 100644 man/sd_bus_message_append_basic.xml create mode 100644 man/sd_bus_message_append_string_memfd.xml create mode 100644 man/sd_bus_message_append_strv.xml (limited to 'man') diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml new file mode 100644 index 0000000000..2a1e95aa35 --- /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 0000000000..fe84671f3e --- /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 0000000000..a8e91f9e97 --- /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 0000000000..a9b8924805 --- /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 0000000000..048bbcac08 --- /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 + + + + -- cgit v1.2.3-54-g00ecf