HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |REFERENCE OWNERSHIP |NOTES |HISTORY |SEE ALSO |NOTES |COLOPHON | |
SD_BUS_C..._FROM_PID(3) sd_bus_creds_new_from_pidSD_BUS_C..._FROM_PID(3)sd_bus_creds_new_from_pid, sd_bus_creds_new_from_pidfd, sd_bus_creds_get_mask, sd_bus_creds_get_augmented_mask, sd_bus_creds_ref, sd_bus_creds_unref, sd_bus_creds_unrefp - Retrieve credentials object for the specified PID
#include <systemd/sd-bus.h>int sd_bus_creds_new_from_pid(pid_tpid, uint64_tcreds_mask,sd_bus_creds **ret);int sd_bus_creds_new_from_pidfd(intpidfd, uint64_tcreds_mask,sd_bus_creds **ret);uint64_t sd_bus_creds_get_mask(sd_bus_creds *c);uint64_t sd_bus_creds_get_augmented_mask(sd_bus_creds *c);sd_bus_creds *sd_bus_creds_ref(sd_bus_creds *c);sd_bus_creds *sd_bus_creds_unref(sd_bus_creds *c);void sd_bus_creds_unrefp(sd_bus_creds **c);SD_BUS_CREDS_PID,SD_BUS_CREDS_PPID,SD_BUS_CREDS_TID,SD_BUS_CREDS_UID,SD_BUS_CREDS_EUID,SD_BUS_CREDS_SUID,SD_BUS_CREDS_FSUID,SD_BUS_CREDS_GID,SD_BUS_CREDS_EGID,SD_BUS_CREDS_SGID,SD_BUS_CREDS_FSGID,SD_BUS_CREDS_SUPPLEMENTARY_GIDS,SD_BUS_CREDS_COMM,SD_BUS_CREDS_TID_COMM,SD_BUS_CREDS_EXE,SD_BUS_CREDS_CMDLINE,SD_BUS_CREDS_CGROUP,SD_BUS_CREDS_UNIT,SD_BUS_CREDS_SLICE,SD_BUS_CREDS_USER_UNIT,SD_BUS_CREDS_USER_SLICE,SD_BUS_CREDS_SESSION,SD_BUS_CREDS_OWNER_UID,SD_BUS_CREDS_EFFECTIVE_CAPS,SD_BUS_CREDS_PERMITTED_CAPS,SD_BUS_CREDS_INHERITABLE_CAPS,SD_BUS_CREDS_BOUNDING_CAPS,SD_BUS_CREDS_SELINUX_CONTEXT,SD_BUS_CREDS_AUDIT_SESSION_ID,SD_BUS_CREDS_AUDIT_LOGIN_UID,SD_BUS_CREDS_TTY,SD_BUS_CREDS_UNIQUE_NAME,SD_BUS_CREDS_WELL_KNOWN_NAMES,SD_BUS_CREDS_DESCRIPTION,SD_BUS_CREDS_PIDFD,SD_BUS_CREDS_AUGMENT,_SD_BUS_CREDS_ALL
sd_bus_creds_new_from_pid()creates a new credentials object and fills it with information about the processpid. The pointer to this object will be stored in theret pointer. Note that credential objects may also be created and retrieved viasd_bus_get_name_creds(3),sd_bus_get_owner_creds(3) andsd_bus_message_get_creds(3).sd_bus_creds_new_from_pidfd()is identical tosd_bus_creds_new_from_pid(), but takes a PID file descriptor rather than a numeric PID as reference to the process. Seepidfd_open(2). The information that will be stored is determined bycreds_mask. It may contain a subset of ORed constantsSD_BUS_CREDS_PID,SD_BUS_CREDS_PPID,SD_BUS_CREDS_TID,SD_BUS_CREDS_UID,SD_BUS_CREDS_EUID,SD_BUS_CREDS_SUID,SD_BUS_CREDS_FSUID,SD_BUS_CREDS_GID,SD_BUS_CREDS_EGID,SD_BUS_CREDS_SGID,SD_BUS_CREDS_FSGID,SD_BUS_CREDS_SUPPLEMENTARY_GIDS,SD_BUS_CREDS_COMM,SD_BUS_CREDS_TID_COMM,SD_BUS_CREDS_EXE,SD_BUS_CREDS_CMDLINE,SD_BUS_CREDS_CGROUP,SD_BUS_CREDS_UNIT,SD_BUS_CREDS_SLICE,SD_BUS_CREDS_USER_UNIT,SD_BUS_CREDS_USER_SLICE,SD_BUS_CREDS_SESSION,SD_BUS_CREDS_OWNER_UID,SD_BUS_CREDS_EFFECTIVE_CAPS,SD_BUS_CREDS_PERMITTED_CAPS,SD_BUS_CREDS_INHERITABLE_CAPS,SD_BUS_CREDS_BOUNDING_CAPS,SD_BUS_CREDS_SELINUX_CONTEXT,SD_BUS_CREDS_AUDIT_SESSION_ID,SD_BUS_CREDS_AUDIT_LOGIN_UID,SD_BUS_CREDS_TTY,SD_BUS_CREDS_UNIQUE_NAME,SD_BUS_CREDS_WELL_KNOWN_NAMES,SD_BUS_CREDS_DESCRIPTION, andSD_BUS_CREDS_PIDFD. Use the special value_SD_BUS_CREDS_ALLto request all supported fields. TheSD_BUS_CREDS_AUGMENTconstant may not be ORed into the mask for invocations ofsd_bus_creds_new_from_pid()orsd_bus_creds_new_from_pidfd(). Fields can be retrieved from the credentials object usingsd_bus_creds_get_pid(3) and other functions which correspond directly to the constants listed above. A mask of fields which were actually successfully retrieved can be retrieved withsd_bus_creds_get_mask(). If the credentials object was created withsd_bus_creds_new_from_pid()orsd_bus_creds_new_from_pidfd(), this will be a subset of fields requested increds_mask. Similar tosd_bus_creds_get_mask(), the functionsd_bus_creds_get_augmented_mask()returns a bitmask of field constants. The mask indicates which credential fields have been retrieved in a non-atomic fashion. For credential objects created viasd_bus_creds_new_from_pid()orsd_bus_creds_new_from_pidfd(), this mask will be identical to the mask returned bysd_bus_creds_get_mask(). However, for credential objects retrieved viasd_bus_get_name_creds(), this mask will be set for the credential fields that could not be determined atomically at peer connection time, and which were later added by reading augmenting credential data from /proc/. Similarly, for credential objects retrieved viasd_bus_get_owner_creds(), the mask is set for the fields that could not be determined atomically at bus creation time, but have been augmented. Similarly, for credential objects retrieved viasd_bus_message_get_creds(), the mask is set for the fields that could not be determined atomically at message sending time, but have been augmented. The mask returned bysd_bus_creds_get_augmented_mask()is always a subset of (or identical to) the mask returned bysd_bus_creds_get_mask()for the same object. The latter call hence returns all credential fields available in the credential object, the former then marks the subset of those that have been augmented. Note that augmented fields are unsuitable for authorization decisions, as they may be retrieved at different times, thus being subject to races. Hence, augmented fields should be used exclusively for informational purposes.sd_bus_creds_ref()creates a new reference to the credentials objectc. This object will not be destroyed untilsd_bus_creds_unref()has been called as many times plus once more. Once the reference count has dropped to zero,c cannot be used anymore, so further calls tosd_bus_creds_ref(c)orsd_bus_creds_unref(c)are illegal.sd_bus_creds_unref()destroys a reference toc.sd_bus_creds_unrefp()is similar tosd_bus_creds_unref()but takes a pointer to a pointer to ansd_bus_credsobject. This call is useful in conjunction with GCC's and LLVM'sClean-up VariableAttribute[1]. Note that this function is defined as inline function.sd_bus_creds_ref(),sd_bus_creds_unref()andsd_bus_creds_unrefp() execute no operation if the passed in bus credentials object isNULL.
On success,sd_bus_creds_new_from_pid()andsd_bus_creds_new_from_pidfd()return 0 or a positive integer. On failure, they return a negative errno-style error code.sd_bus_creds_get_mask()returns the mask of successfully acquired fields.sd_bus_creds_get_augmented_mask()returns the mask of fields that have been augmented from data in /proc/, and are thus not suitable for authorization decisions.sd_bus_creds_ref()always returns the argument.sd_bus_creds_unref()always returnsNULL.
The functionssd_bus_creds_new_from_pid()andsd_bus_creds_new_from_pidfd()create a new object and the caller owns the sole reference. When not needed anymore, this reference should be destroyed withsd_bus_creds_unref(3).Errors Returned errors may indicate the following problems:-ESRCH Specifiedpid could not be found.-EINVAL Specified parameter is invalid (NULLin case of output parameters).-ENOMEM Memory allocation failed.-EOPNOTSUPP One of the requested fields is unknown to the local system.
Functions described here are available as a shared library, which can be compiled against and linked to with thelibsystemd pkg-config(1) file. The code described here usesgetenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not callsetenv(3) from a parallel thread. It is recommended to only do calls tosetenv()from an early phase of the program when no other threads have been started.
sd_bus_creds_new_from_pid(),sd_bus_creds_get_mask(),sd_bus_creds_ref(),sd_bus_creds_unref(), andsd_bus_creds_get_augmented_mask()were added in version 221.sd_bus_creds_unrefp()was added in version 229.sd_bus_creds_new_from_pidfd()was added in version 256.
systemd(1),sd-bus(3),sd_bus_creds_get_pid(3),sd_bus_get_name_creds(3),sd_bus_get_owner_creds(3),sd_bus_message_get_creds(3)
1. Clean-up Variable Attributehttps://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
This page is part of thesystemd (systemd system and service manager) project. Information about the project can be found at ⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug report for this manual page, see ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This page was obtained from the project's upstream Git repository ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-11.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgsystemd 258~rc2SD_BUS_C..._FROM_PID(3)Pages that refer to this page:sd-bus(3), sd_bus_creds_get_pid(3), sd_bus_creds_new_from_pid(3), sd_bus_get_name_creds(3), sd_bus_query_sender_creds(3), systemd.directives(7), systemd.index(7)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |