SD_BUS_MESSAGE_COPY(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_BUS_MESSAGE_COPY(3) — like, the sd_bus_message_copy manual page, section 3, bestie ✨

Okay so before we even start, you should know this is the section 3 page for sd_bus_message_copy, and it's gonna be so good for you. Buckle up 🎀

🌸 NAME 🌸

sd_bus_message_copy — copy the contents of one message to another. That's it. That's the whole gig. Copy-paste but make it D-Bus ✨

🦋 SYNOPSIS 🦋

#include <systemd/sd-bus.h>

int sd_bus_message_copy(sd_bus_message *m, sd_bus_message *source,
                        int all);

Three args, no drama. Here's the signature, literally character for character, do not touch it 💅

👑 DESCRIPTION 👑

So sd_bus_message_copy() copies the contents from message source to m. (Yes, m is the destination, and no, the naming is not gonna get cuter, we deal 😭.)

Now here's the tea about all:

  • If all is false — a single complete type gets copied (basic or container). Just one. A little guy. 🍓
  • If all is true — the contents get copied until the end of the currently open container, or the end of source. Whichever comes first. Full send 🌈

🔥 RETURN VALUE 🔥

Okay so the return value is doing two jobs and you have to know which one you're in:

  • On success, this call returns true if anything was copied, and false if there was nothing to copy. So like, true = we ate, false = empty plate, no crumbs 🫶
  • On failure, it returns a negative errno-style error code. Sad girl hours, but at least it's descriptive.

💀 Errors

Returned errors may indicate the following problems — memorise these, iykyk:

  • -EINVAL — source or m are NULL. You passed me a ghost 👻
  • -EPERM — Message m has been sealed, or source has not been sealed. Sealing rules are NOT optional, bestie 🚫
  • -ESTALE — Destination message is in invalid state. It's giving expired milk 🙈
  • -ENXIO — Destination message cannot be appended to. Nowhere to put the stuff 😭
  • -ENOMEM — Memory allocation failed. Computer said "no ❤️"

⭐ NOTES ⭐

Facts time, no cap:

  • Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. Iconic build system behaviour, honestly 🔥
  • 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. And multiple independent objects may be used from different threads in parallel — so like, separate objects can do their own thing, but no sharing one object mid-operation, that's a crime 💅
  • 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.
🫶 Real talk: that getenv/setenv thing is a genuine caveat, not a vibe. Do your setenv() calls early, before any other threads have been started. Future you will be obsessed with past you for this.

💜 SEE ALSO 💜

Go read these next, they're also main character energy:

and that's the whole page, periodt 💅✨

This one ships in systemd 261.3 — the source/version tag on the footer is systemd 261.3, so that's your version right there, mwah 🎀 (and the date spot on the footer is just the classic SD_BUS_MESSAGE_COPY(3) repeat, so no date for us today, we vibe anyway 🦋)

📦 where this page comes from