SD_BUS_QU...NDER_CREDS(3)

💅 sd_bus_query_sender_creds, sd_bus_query_sender_privilege — query bus message sender credentials/privileges

okay so bestie, grab your iced coffee 🍓 because we're diving into the sd_bus_query_sender_creds family — that's sd_bus_query_sender_creds and sd_bus_query_sender_privilege, both living their best life in the sd_bus_query_sender_creds section of the systemd manuals. yes, the header repeats the name like three times, that's just how manpages are. iconic behavior honestly 👑

---

✨ SYNOPSIS ✨

#include <systemd/sd-bus.h>

int sd_bus_query_sender_creds(sd_bus_message *m, uint64_t mask,
                              sd_bus_creds **creds);

sd_bus_error* sd_bus_query_sender_privilege(sd_bus_message *m,
                                            int capability);

---

🌸 DESCRIPTION 🌸

🫶 sd_bus_query_sender_creds()

so this one returns the credentials of the message m, okay? and the mask parameter? that's a little combo of SD_BUS_CREDS_* flags that tells everyone which credential info the caller is actually interested in. wanna see the full list of possible flags? go peek at sd_bus_creds_new_from_pid(3), it's all there 💖

now the way this works is lowkey a little detective story:

• first, it checks if the requested credentials are already attached to the message itself. easy, no notes 💅
• if not, but the message contains the pid of the sender and the caller specified the SD_BUS_CREDS_AUGMENT flag, the function tries to figure out the missing credentials via other means (starting from the pid). main character detective energy fr fr 🔍
• if the PID is not available but the message has a sender, this function calls sd_bus_get_name_creds(3) to get the requested credentials.
• if the message has no sender (this is the direct-connection girlies), this function calls sd_bus_get_owner_creds(3) to get the requested credentials.

on success, the requested credentials are stored in creds. and the ownership of that credentials object in creds is transferred to the caller — so you gotta free it by calling sd_bus_creds_unref(3). don't ghost it, clean up after yourself 🧹✨

🦋 sd_bus_query_sender_privilege()

this one checks if the message m has the requested privileges. here's the tea:

• if capability is a non-negative integer, it checks if the message has the capability with the same value. see capabilities(7) for a list of capabilities 📋
• if capability is a negative integer, it returns whether the sender of the message runs as the same user as the receiver of the message, or whether the sender of the message runs as root and the receiver of the message does not run as root. root girlies stay winning 👑

on success and if the message has the requested privileges, this function returns a positive integer (slay). if the message does not have the requested privileges, it returns zero. no cap. 🫡

---

⭐ RETURN VALUE ⭐

on success, these functions return a non-negative integer. on failure, they return a negative errno-style error code. the duality of life 😭

💀 Errors

returned errors may indicate the following problems, bestie — write these down:

• -EINVAL — the message m or an output parameter is NULL.

added in version 246.

• -ENOTCONN — the bus of m is not connected.

added in version 246.

• -ECHILD — the bus of m was created in a different process, library or module instance. rude, honestly 🙈

added in version 246.

• -EPERM — the message m is not sealed.

added in version 246.

---

🎀 NOTES 🎀

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. build system besties, that one's for you 🛠️

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. sharing is caring but also read the rules 💖

⚠️ heads up babes: the code described here uses getenv(3), which is declared to be not multi-thread-safe. that 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 with that information what you will, but like, please do it correctly 😭

---

🌈 HISTORY 🌈

sd_bus_query_sender_creds() and sd_bus_query_sender_privilege() were added in version 246. glow-up era ✨

---

👑 SEE ALSO 👑

systemd(1), sd-bus(3), sd_bus_creds_new_from_pid(3), sd_bus_get_name_creds(3), sd_bus_get_owner_creds(3), sd_bus_creds_unref(3), capabilities(7)

---

okay that's the whole page, bestie, you ate that 🍓💅 this little number is from systemd 261.3, dated the systemd 261.3 era, and if you ever forget, just remember: this manual page itself is literally called SD_BUS_QU...NDER_CREDS(3) — the abbreviated icon it is 💜🦋 periodt 🌸