SD_BUS_MESSAGE_APPEND(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

👑 NAME 👑

Okay bestie, this is the manual page for sd_bus_message_append(3) — and its ride-or-die sd_bus_message_appendv is right here too. The whole point: Attach fields to a D-Bus message based on a type string. Periodt. 💅

🧚 SYNOPSIS 🧚

#include <systemd/sd-bus.h>

int sd_bus_message_append(sd_bus_message *m, const char *types, ...);

int sd_bus_message_appendv(sd_bus_message *m, const char *types,
                           va_list ap);

🔥 DESCRIPTION 🔥

So sd_bus_message_append() 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. Literally match the order, bestie — no chaos. ✨

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. 🎀

  • Basic type — in case of a basic type, one argument of the corresponding type is expected. Simple. Iconic. 💖
  • Structure — 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. Nested but not messy, iykyk. 🦋
  • Variant — 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. It's giving "type reveal" energy. 🌸
  • 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. Count first, then the entries — no cap. 🔥
  • Dictionary — 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. Pair by pair, slay. 👑

sd_bus_message_appendv() is equivalent to sd_bus_message_append(), except that it is called with a va_list instead of a variable number of arguments. 🚨 Real talk: 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. Not me warning you dramatically, but also yes. 😭

For further details on the D-Bus type system, please consult the D-Bus Specification[1]. 💜

🎀 Table 1. Item type specifiers 🎀

okay bestie, this is the cheat sheet for every type-string character — specifier, constant, meaning, size, and the C type you should expect. no skips, this is the whole table:

  • "y" — constant SD_BUS_TYPE_BYTE; unsigned integer; size: 1 byte; expected C type: uint8_t.
  • "b" — constant SD_BUS_TYPE_BOOLEAN; boolean; size: 4 bytes; expected C type: int.
  • "n" — constant SD_BUS_TYPE_INT16; signed integer; size: 2 bytes; expected C type: int16_t.
  • "q" — constant SD_BUS_TYPE_UINT16; unsigned integer; size: 2 bytes; expected C type: uint16_t.
  • "i" — constant SD_BUS_TYPE_INT32; signed integer; size: 4 bytes; expected C type: int32_t.
  • "u" — constant SD_BUS_TYPE_UINT32; unsigned integer; size: 4 bytes; expected C type: uint32_t.
  • "x" — constant SD_BUS_TYPE_INT64; signed integer; size: 8 bytes; expected C type: int64_t.
  • "t" — constant SD_BUS_TYPE_UINT64; unsigned integer; size: 8 bytes; expected C type: uint64_t.
  • "d" — constant SD_BUS_TYPE_DOUBLE; floating-point; size: 8 bytes; expected C type: double.
  • "s" — constant SD_BUS_TYPE_STRING; Unicode string; size: variable; expected C type: char[].
  • "o" — constant SD_BUS_TYPE_OBJECT_PATH; object path; size: variable; expected C type: char[].
  • "g" — constant SD_BUS_TYPE_SIGNATURE; signature; size: variable; expected C type: char[].
  • "h" — constant SD_BUS_TYPE_UNIX_FD; UNIX file descriptor; size: 4 bytes; expected C type: int.
  • "a" — constant SD_BUS_TYPE_ARRAY; array; size: determined by array type and size; expected C type: int, followed by array contents.
  • "v" — constant SD_BUS_TYPE_VARIANT; variant; size: determined by the type argument; expected C type: signature string, followed by variant contents.
  • "(" — constant SD_BUS_TYPE_STRUCT_BEGIN; array start; size: determined by the nested types; expected C type: structure contents.
  • ")" — constant SD_BUS_TYPE_STRUCT_END; array end; size: determined by the nested types; expected C type: structure contents.
  • "{" — constant SD_BUS_TYPE_DICT_ENTRY_BEGIN; dictionary entry start; size: determined by the nested types; expected C type: dictionary contents.
  • "}" — constant SD_BUS_TYPE_DICT_ENTRY_END; dictionary entry end; size: determined by the nested types; expected C type: dictionary contents.

okay so for types "s" and "g" (unicode string or signature), the pointer may be NULL, which is equivalent to an empty string. for "h" (UNIX file descriptor), the descriptor is duplicated by this call and the passed descriptor stays in possession of the caller. see sd_bus_message_append_basic(3) for the precise interpretation of those and other types. 💅

🌈 TYPES STRING GRAMMAR 🌈

this is the literal grammar vibe check for type strings, so copy it exactly — every character counts:

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 💖

okay bestie, this is the part where it all clicks. real code, real vibes ✨

Append a single basic type (the string "a string"):

sd_bus_message *m;
...
sd_bus_message_append(m, "s", "a string");

one string, one call, done. we love a low-effort icon 💅

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);

look at that type string just eating all those variables in order 🍓 like, ynqiuxtd is genuinely giving alphabet soup but she's correct, ok? each letter matches its variable, one for one, no skipping 🫶

Append a structure composed of a string and a D-Bus path:

sd_bus_message_append(m, "(so)", "a string", "/a/path");

parentheses = struct, s = string, o = path. that's it, that's the whole meal 🔥

Append an array of UNIX file descriptors:

sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);

see how the array needs its length 3 first, and then the elements? yeah. that's the rule for arrays, no cap. the h letter is the UNIX file descriptor type btw 💀

Append a variant, with the real type "g" (signature), and value "sdbusisgood":

sd_bus_message_append(m, "v", "g", "sdbusisgood");

a variant is literally just "surprise, here's the actual type" — so you pass v, then the signature string "g", then the value. and the value is "sdbusisgood" because of course it is 😭 iconic behavior honestly

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);

so a{is} is an array of dict entries from int → string. count first (3), then key/value, key/value, key/value. and notice the last value is NULL — that empty string is being passed as a null pointer, not a "". she's built different 🙈

🌈 RETURN VALUE 🌈

On success, these functions return a non-negative integer. on failure? they return a negative errno-style error code. simple as that, bestie 💜

🎀 Errors 🎀

Returned errors may indicate the following problems:

  • -EINVAL — Specified parameter is invalid. (something you handed over just doesn't check out)
  • -EPERM — Message has been sealed. (sealed = locked, and she is not letting you in 🔒)
  • -ESTALE — Message is in invalid state.
  • -ENXIO — Message cannot be appended to.
  • -ENOMEM — Memory allocation failed. (the classic 😭)

✨ NOTES ✨

Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. so yes, you do need to link her properly, don't just vibe and hope 🫶

Thread tea ☕ — All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time. Different threads may access the same object at different times. Multiple independent objects may be used from different threads in parallel. translation: one object = one thread at a time, but different objects can party in parallel, no drama 💅

⚠️ okay important one: the code described here uses getenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) from a parallel thread. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. so like... set your env vars early, before the threads wake up, or it's giving chaos 🙈

👑 SEE ALSO 👑

systemd(1), sd-bus(3), sd_bus_message_append_basic(3), sd_bus_message_append_array(3), sd_bus_message_open_container(3)

go read the rest of the family, they all ate ⭐

📎 NOTES 📎

(yeah there's a second one, it's the footnote section, stay with me 🧚)

  1. D-Bus Specification — https://dbus.freedesktop.org/doc/dbus-specification.html#type-system

and that's the whole page, bestie! 🎀 this lil masterpiece is from systemd 261.3, and it's the SD_BUS_MESSAGE_APPEND(3) manual page — go forth and append responsibly, mwah 💖🦋

📦 where this page comes from