SD_BUS_ME...PEND_BASIC(3)

🌸 NAME 🌸

okay so bestie, welcome to the sd_bus_message_append_basic page (that's SD_BUS_ME...PEND_BASIC(3) in the manual, section 3 — the truncated name is literally how it shows up in the header, iykyk 💅). this one does exactly what it says on the tin:

sd_bus_message_append_basic — Attach a single field to a message ✨

---

🎀 SYNOPSIS 🎀

#include <systemd/sd-bus.h>

int sd_bus_message_append_basic(sd_bus_message *m, char type,
                                const void *p);

---

🦋 DESCRIPTION 🦋

okay so sd_bus_message_append_basic() appends a single field to the message m. one field. one. don't get greedy 🔥

the parameter type is the main character here — it decides how the pointer p gets interpreted 👑. type has got to be one of the basic types as defined by the Basic Types[1] section of the D-Bus specification, and they're all listed in the very cute table below 💖.

Table 1. Item type specifiers (the whole squad, no gatekeeping):

• "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

so here's the vibe on copying 🫶: the value of the parameter gets copied into a memory area held by the message object. so the value stays in the possession of the caller — meaning you can freely change it after this call and the bus message you already added it to will not care one bit, no cap ✨. and if type is "h" (UNIX file descriptor), the descriptor is duplicated by this call, and the descriptor you passed stays in possession of the caller. slay, no dangling FDs 💅.

for types "s", "o", and "g", the parameter p is interpreted as a pointer to a NUL-terminated character sequence. and as a special case, a NULL pointer is interpreted as an empty string 🙈. the string should be a valid Unicode string encoded as UTF-8. and for the two latter types ("o" and "g"), the additional requirements for a D-Bus object path or type signature should be satisfied too. those requirements should be verified by the recipient of the message — that's their job, not yours, bestie 😭

---

⭐ 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. (no editing, it's locked, periodt 🔒)
• -ESTALE — message is in invalid state.
• -ENXIO — message cannot be appended to.
• -ENOMEM — memory allocation failed.

---

🧚 NOTES 🧚

the functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file 🌈.

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 — so like, share the objects, don't share the moment 🫶.

⚠️ okay this part matters so listen up: the code described here uses getenv(3), which is declared to be not multi-thread-safe. this means 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. highkey do this early, bestie 💀

---

💜 SEE ALSO 💜

systemd(1), sd-bus(3), sd_bus_message_read_basic(3), sd_bus_message_append(3), The D-Bus specification[2]

---

🍓 NOTES 🍓

1. Basic Types — https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
2. The D-Bus specification — https://dbus.freedesktop.org/doc/dbus-specification.html

---

and that's the whole page, bestie — brought to you by systemd 261.3 on the SD_BUS_ME...PEND_BASIC(3) manual page, go append something iconic today 💅✨🎀