SD_BUS_SET_DESCRIPTION(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_BUS_SET_DESCRIPTION(3) 💅

okay so bestie, welcome to sd_bus_set_description(3) — one of those sd-bus pages where a whole little squad of functions share one manpage because they're all about setting or querying properties of a bus object. yes, all of them. no, i'm not kidding. buckle up 🎀

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_set_description(sd_bus *bus, const char *description);

int sd_bus_get_description(sd_bus *bus, const char **description);

int sd_bus_set_anonymous(sd_bus *bus, int b);

int sd_bus_is_anonymous(sd_bus *bus);

int sd_bus_set_trusted(sd_bus *bus, int b);

int sd_bus_is_trusted(sd_bus *bus);

int sd_bus_set_allow_interactive_authorization(sd_bus *bus, int b);

int sd_bus_get_allow_interactive_authorization(sd_bus *bus);

int sd_bus_get_scope(sd_bus *bus, const char **scope);

int sd_bus_get_tid(sd_bus *bus, pid_t *tid);

int sd_bus_get_unique_name(sd_bus *bus, const char **unique);

like, that's eleven functions. eleven!! and every single one of them is getting its moment below, don't worry 💖

🦋 DESCRIPTION 🦋

🌸 the description ones

sd_bus_set_description() sets the description string that gets used in logging, to whatever string you hand it. the string gets copied internally and freed when the bus object is deallocated — so it's not keeping a pointer to your buffer, bestie, it's making its own little copy. the description argument may be NULL, and in that case the description is just unset. literally that simple. this function must be called before the bus is started though, okay? that's the rule 🔥

sd_bus_get_description() returns a description string in description. this string may have been previously set with sd_bus_set_description() or sd_bus_open_with_description(3) or similar. and if it was not set that way? then a default string like "system" or "user" will be returned for the system or user buses, and you get -ENXIO otherwise. iykyk 😌

🙈 the anonymous ones

sd_bus_set_anonymous() enables or disables "anonymous authentication" — which is a fancy way of saying lack of authentication — of the bus peer. and yes, this one also must be called before the bus is started. peep the D-Bus Authentication Mechanisms[1] section of the D-Bus specification for the deets.

sd_bus_is_anonymous() returns true if the bus connection allows anonymous authentication (in the sense described in the previous paragraph, obviously 💅).

👑 the trusted ones

sd_bus_set_trusted() sets the "trusted" state on the bus object. if true, all connections on the bus are trusted and access to all privileged and unprivileged methods is granted. big main character energy, honestly. this function must be called before the bus is started too.

sd_bus_is_trusted() returns true if the bus connection is trusted (again, in the sense described in the previous paragraph).

🫶 the interactive authorization ones

sd_bus_set_allow_interactive_authorization() enables or disables interactive authorization for method calls. if true, messages are marked with the ALLOW_INTERACTIVE_AUTHORIZATION flag specified by the D-Bus[2] specification, informing the receiving side that the caller is prepared to wait for interactive authorization — which might take a considerable time to complete. like, considerable. don't be surprised. if this flag is set, the user may be queried for passwords or confirmation via polkit[3] or a similar framework.

sd_bus_get_allow_interactive_authorization() returns true if interactive authorization is allowed, and false if not. short and sweet 🍓

🔥 the scope one

sd_bus_get_scope() stores the scope of the given bus object in scope. the scope of the system bus is "system". the scope of a user session bus is "user". and if the given bus object is not the system bus or a user session bus? then sd_bus_get_scope() returns an error. no scope for you 💀

⭐ the tid one

sd_bus_get_tid() stores the kernel thread id of the thread associated with the given bus object in tid. here's the vibe check on which thread it means:

  • if bus is a default bus object obtained by calling one of the functions of the sd_bus_default(3) family of functions, it stores the thread id of the thread the bus object was created in.
  • otherwise, if the bus object is attached to an event loop, it stores the thread id of the thread the event loop object was created in.
  • and if bus is not a default bus object and is not attached to an event loop? sd_bus_get_tid() returns an error. sorry bestie 😭

🧚 the unique name one

sd_bus_get_unique_name() stores the unique name of the bus object on the bus in unique. see The D-Bus specification[4] for more info on bus names. note that the caller does not own the string stored in unique and should not free it. do not free it. i'm serious. don't 💜

🌈 RETURN VALUE 🌈

on success, these functions return a non-negative integer. on failure, they return a negative errno-style error code. that's it, that's the contract 🎀

💅 Errors

returned errors may indicate the following problems:

  • -EINVAL — an argument is invalid. classic.
  • -ENOPKG — the bus cannot be resolved.
  • -EPERM — the bus has already been started. you were too late, bestie 🫶
  • -ECHILD — the bus was created in a different process, library or module instance. not your bus, not your problem.
  • -ENOMEM — memory allocation failed. it happens to the best of us.
  • -ENODATA — the bus object passed to sd_bus_get_scope() was not a system or user session bus. Added in version 246.
  • -ENXIO — two whole situations here, so pay attention:
    • the bus object passed to sd_bus_get_tid() was not a default bus object and is not attached to an event loop.
    • the bus object passed to sd_bus_get_description() did not have a description.

Added in version 246.

🌸 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. slay.

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, share the object politely, bestie ✨

⚠️ okay this part matters: 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. like, do it before the party starts, not during 🎉

🔥 HISTORY 🔥

  • sd_bus_set_description(), sd_bus_get_description(), sd_bus_set_anonymous(), sd_bus_set_trusted(), sd_bus_set_allow_interactive_authorization(), and sd_bus_get_allow_interactive_authorization() were added in version 240.
  • sd_bus_is_anonymous(), sd_bus_is_trusted(), sd_bus_get_scope(), sd_bus_get_tid(), and sd_bus_get_unique_name() were added in version 246.

🦋 SEE ALSO 🦋

systemd(1), sd-bus(3), sd_bus_default_user(3), sd_bus_default_system(3), sd_bus_open_user(3), sd_bus_open_system(3)

🔗 NOTES (the footnote kind) 🔗

  1. D-Bus Authentication Mechanisms — view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms
  2. D-Bus — view-source:https://dbus.freedesktop.org/doc/dbus-specification.html
  3. polkit — https://www.freedesktop.org/wiki/Software/polkit
  4. The D-Bus specification — https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus

okay that's the whole page, go forth and set your descriptions before the bus starts, bestie 💖 this has been systemd 261.3 — SD_BUS_SET_DESCRIPTION(3) — signing off, periodt 🎀✨

📦 where this page comes from