SD_BUS_M...HOD_ERROR(3)

📦
version 261.3 · 17 versions
, in ubuntu stonking

💅 SD_BUS_M...HOD_ERROR(3) — the sd_bus_message_new_method_error girlies ✨

okay so bestie, welcome to the systemd manual page for sd_bus_message_new_method_error, sd_bus_message_new_method_errorf, sd_bus_message_new_method_errno, and sd_bus_message_new_method_errnof. this is a sd-bus (that's sd-bus(3), ily) thing and it's literally all about making error replies for method calls. no cap. 🎀

🌸 NAME 🌸

sd_bus_message_new_method_error, sd_bus_message_new_method_errorf, sd_bus_message_new_method_errno, sd_bus_message_new_method_errnof — Create an error reply for a method call 💖

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_message_new_method_error(sd_bus_message *call,
                                    sd_bus_message **m,
                                    const sd_bus_error *e);

int sd_bus_message_new_method_errorf(sd_bus_message *call,
                                     sd_bus_message **m,
                                     const char *name,
                                     const char *format, ...);

int sd_bus_message_new_method_errno(sd_bus_message *call,
                                    sd_bus_message **m, int error,
                                    const sd_bus_error *p);

int sd_bus_message_new_method_errnof(sd_bus_message *call,
                                     sd_bus_message **m, int error,
                                     const char *format, ...);

like, four functions, one vibe. let's get into it. 🦋

🫶 DESCRIPTION 🫶

💌 sd_bus_message_new_method_error()

so this one creates a new bus message object that is an error reply to the call message, and hands it back to you in the m output parameter. iconic.

the error info from the error e gets appended: the name field of e is used as the error identifier in the reply header (think an error name like "org.freedesktop.DBus.Error.NotSupported", or the equivalent symbolic SD_BUS_ERROR_NOT_SUPPORTED), and the message field is set as the human-readable error message string if present. 👑

⚠️ real talk — the error e must have the name field set. check it with sd_bus_error_is_set(3) first, bestie, don't get caught slipping.

💌 sd_bus_message_new_method_errorf()

creates an error reply similarly to sd_bus_message_new_method_error(), except instead of a ready-made error structure, it takes an error identifier string name, plus a printf(3) format string format and the corresponding arguments. so you send an error reply with the error identifier name and the formatted string as the message. ✨

name and format must not be NULL. literally do not. 🚫

💌 sd_bus_message_new_method_errno()

creates an error reply similarly to sd_bus_message_new_method_error(), but on top of the error structure p, it also takes an errno(3) error value in the parameter error. here's the tea 🍓:

  • if the error p is set (again, see sd_bus_error_is_set(3)), it's used in the reply.
  • otherwise, error is translated into an error identifier and used to create a new error structure via sd_bus_error_set_errno(3), and that is used in the reply.

and if error is zero? no error is actually set, and you get an error reply with no information. it's giving empty message energy, but that's valid. 💀

💌 sd_bus_message_new_method_errnof()

creates an error reply similarly to sd_bus_message_new_method_error(). it takes an errno(3) error value in the parameter error, plus a printf(3) format string format and corresponding arguments. you can use "%m" in the format string to refer to the error string corresponding to the specified errno code. 🌈

the error message is initialized using the error identifier generated from error and the formatted string. (if error is zero, no error is actually set, and an error reply with no information is created — same deal as above, fr fr.)

🔥 RETURN VALUE 🔥

these functions return 0 if the error reply was successfully created, and a negative errno-style error code otherwise. slay when it works, sigh when it doesn't. 😭

🌸 Errors 🌸

returned errors may indicate the following problems:

  • -EINVAL — the call message call or the output parameter m are NULL. also: message call is not a method call message. also also: the error e parameter to sd_bus_message_new_method_error() is not set, see sd_bus_error_is_set(3). three-for-one problem, not the fun kind of combo. 🙈
  • -EPERM — message call has been sealed. it's locked, bestie, no touching. 🔒
  • -ENOTCONN — the bus to which message call is attached is not connected. the vibe check failed. 💀
  • -ENOMEM — memory allocation failed. the malloc said no. 😭

👑 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 object, not the moment. 🧚
  • 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's recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. do it early or don't do it, iykyk. ⭐

🌈 SEE ALSO 🌈

systemd(1), sd-bus(3)

and that's the whole page, bestie!! 🎀💖✨ this was systemd 261.3, documented under SD_BUS_M...HOD_ERROR(3) — go forth and error-reply responsibly, mwah 💅🫶

📦 where this page comes from