X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=man%2Fsd_bus_message_append.xml;fp=man%2Fsd_bus_message_append.xml;h=2a1e95aa35de4fc461d31f16d47118d17c2bb2a6;hb=effbc8e4f70fc70e4a4a8a1dc77228dd187f9c22;hp=0000000000000000000000000000000000000000;hpb=a0e5b17733f2146d727edfdb0ebf8482a8c3bf6c;p=elogind.git 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 + + + +