'\" t
.TH "SD_BUS_CREDS_GET_PID" "3" "" "systemd 256.7" "sd_bus_creds_get_pid"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_bus_creds_get_pid, sd_bus_creds_get_pidfd_dup, sd_bus_creds_get_ppid, sd_bus_creds_get_tid, sd_bus_creds_get_uid, sd_bus_creds_get_euid, sd_bus_creds_get_suid, sd_bus_creds_get_fsuid, sd_bus_creds_get_gid, sd_bus_creds_get_egid, sd_bus_creds_get_sgid, sd_bus_creds_get_fsgid, sd_bus_creds_get_supplementary_gids, sd_bus_creds_get_comm, sd_bus_creds_get_tid_comm, sd_bus_creds_get_exe, sd_bus_creds_get_cmdline, sd_bus_creds_get_cgroup, sd_bus_creds_get_unit, sd_bus_creds_get_slice, sd_bus_creds_get_user_unit, sd_bus_creds_get_user_slice, sd_bus_creds_get_session, sd_bus_creds_get_owner_uid, sd_bus_creds_has_effective_cap, sd_bus_creds_has_permitted_cap, sd_bus_creds_has_inheritable_cap, sd_bus_creds_has_bounding_cap, sd_bus_creds_get_selinux_context, sd_bus_creds_get_audit_session_id, sd_bus_creds_get_audit_login_uid, sd_bus_creds_get_tty, sd_bus_creds_get_unique_name, sd_bus_creds_get_well_known_names, sd_bus_creds_get_description \- Retrieve fields from a credentials object
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-bus\&.h>
.fi
.ft
.HP \w'int\ sd_bus_creds_get_pid('u
.BI "int sd_bus_creds_get_pid(sd_bus_creds\ *" "c" ", pid_t\ *" "pid" ");"
.HP \w'int\ sd_bus_creds_get_pidfd_dup('u
.BI "int sd_bus_creds_get_pidfd_dup(sd_bus_creds\ *" "c" ", int\ *" "ret_fd" ");"
.HP \w'int\ sd_bus_creds_get_ppid('u
.BI "int sd_bus_creds_get_ppid(sd_bus_creds\ *" "c" ", pid_t\ *" "ppid" ");"
.HP \w'int\ sd_bus_creds_get_tid('u
.BI "int sd_bus_creds_get_tid(sd_bus_creds\ *" "c" ", pid_t\ *" "tid" ");"
.HP \w'int\ sd_bus_creds_get_uid('u
.BI "int sd_bus_creds_get_uid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
.HP \w'int\ sd_bus_creds_get_euid('u
.BI "int sd_bus_creds_get_euid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
.HP \w'int\ sd_bus_creds_get_suid('u
.BI "int sd_bus_creds_get_suid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
.HP \w'int\ sd_bus_creds_get_fsuid('u
.BI "int sd_bus_creds_get_fsuid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
.HP \w'int\ sd_bus_creds_get_gid('u
.BI "int sd_bus_creds_get_gid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
.HP \w'int\ sd_bus_creds_get_egid('u
.BI "int sd_bus_creds_get_egid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
.HP \w'int\ sd_bus_creds_get_sgid('u
.BI "int sd_bus_creds_get_sgid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
.HP \w'int\ sd_bus_creds_get_fsgid('u
.BI "int sd_bus_creds_get_fsgid(sd_bus_creds\ *" "c" ", gid_t\ *" "gid" ");"
.HP \w'int\ sd_bus_creds_get_supplementary_gids('u
.BI "int sd_bus_creds_get_supplementary_gids(sd_bus_creds\ *" "c" ", const\ gid_t\ **" "gids" ");"
.HP \w'int\ sd_bus_creds_get_comm('u
.BI "int sd_bus_creds_get_comm(sd_bus_creds\ *" "c" ", const\ char\ **" "comm" ");"
.HP \w'int\ sd_bus_creds_get_tid_comm('u
.BI "int sd_bus_creds_get_tid_comm(sd_bus_creds\ *" "c" ", const\ char\ **" "comm" ");"
.HP \w'int\ sd_bus_creds_get_exe('u
.BI "int sd_bus_creds_get_exe(sd_bus_creds\ *" "c" ", const\ char\ **" "exe" ");"
.HP \w'int\ sd_bus_creds_get_cmdline('u
.BI "int sd_bus_creds_get_cmdline(sd_bus_creds\ *" "c" ", char\ ***" "cmdline" ");"
.HP \w'int\ sd_bus_creds_get_cgroup('u
.BI "int sd_bus_creds_get_cgroup(sd_bus_creds\ *" "c" ", const\ char\ **" "cgroup" ");"
.HP \w'int\ sd_bus_creds_get_unit('u
.BI "int sd_bus_creds_get_unit(sd_bus_creds\ *" "c" ", const\ char\ **" "unit" ");"
.HP \w'int\ sd_bus_creds_get_slice('u
.BI "int sd_bus_creds_get_slice(sd_bus_creds\ *" "c" ", const\ char\ **" "slice" ");"
.HP \w'int\ sd_bus_creds_get_user_unit('u
.BI "int sd_bus_creds_get_user_unit(sd_bus_creds\ *" "c" ", const\ char\ **" "unit" ");"
.HP \w'int\ sd_bus_creds_get_user_slice('u
.BI "int sd_bus_creds_get_user_slice(sd_bus_creds\ *" "c" ", const\ char\ **" "slice" ");"
.HP \w'int\ sd_bus_creds_get_session('u
.BI "int sd_bus_creds_get_session(sd_bus_creds\ *" "c" ", const\ char\ **" "slice" ");"
.HP \w'int\ sd_bus_creds_get_owner_uid('u
.BI "int sd_bus_creds_get_owner_uid(sd_bus_creds\ *" "c" ", uid_t\ *" "uid" ");"
.HP \w'int\ sd_bus_creds_has_effective_cap('u
.BI "int sd_bus_creds_has_effective_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
.HP \w'int\ sd_bus_creds_has_permitted_cap('u
.BI "int sd_bus_creds_has_permitted_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
.HP \w'int\ sd_bus_creds_has_inheritable_cap('u
.BI "int sd_bus_creds_has_inheritable_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
.HP \w'int\ sd_bus_creds_has_bounding_cap('u
.BI "int sd_bus_creds_has_bounding_cap(sd_bus_creds\ *" "c" ", int\ " "capability" ");"
.HP \w'int\ sd_bus_creds_get_selinux_context('u
.BI "int sd_bus_creds_get_selinux_context(sd_bus_creds\ *" "c" ", const\ char\ **" "context" ");"
.HP \w'int\ sd_bus_creds_get_audit_session_id('u
.BI "int sd_bus_creds_get_audit_session_id(sd_bus_creds\ *" "c" ", uint32_t\ *" "sessionid" ");"
.HP \w'int\ sd_bus_creds_get_audit_login_uid('u
.BI "int sd_bus_creds_get_audit_login_uid(sd_bus_creds\ *" "c" ", uid_t\ *" "loginuid" ");"
.HP \w'int\ sd_bus_creds_get_tty('u
.BI "int sd_bus_creds_get_tty(sd_bus_creds\ *" "c" ", const\ char\ **" "tty" ");"
.HP \w'int\ sd_bus_creds_get_unique_name('u
.BI "int sd_bus_creds_get_unique_name(sd_bus_creds\ *" "c" ", const\ char\ **" "name" ");"
.HP \w'int\ sd_bus_creds_get_well_known_names('u
.BI "int sd_bus_creds_get_well_known_names(sd_bus_creds\ *" "c" ", char\ ***" "name" ");"
.HP \w'int\ sd_bus_creds_get_description('u
.BI "int sd_bus_creds_get_description(sd_bus_creds\ *" "c" ", const\ char\ **" "name" ");"
.SH "DESCRIPTION"
.PP
These functions return credential information from an
\fIsd_bus_creds\fR
object\&. Credential objects may be created with
\fBsd_bus_creds_new_from_pid\fR(3), in which case they describe the credentials of the process identified by the specified PID, with
\fBsd_bus_get_name_creds\fR(3), in which case they describe the credentials of a bus peer identified by the specified bus name, with
\fBsd_bus_get_owner_creds\fR(3), in which case they describe the credentials of the creator of a bus, or with
\fBsd_bus_message_get_creds\fR(3), in which case they describe the credentials of the sender of the message\&.
.PP
Not all credential fields are part of every
"sd_bus_creds"
object\&. Use
\fBsd_bus_creds_get_mask\fR(3)
to determine the mask of fields available\&.
.PP
\fBsd_bus_creds_get_pid()\fR
will retrieve the PID (process identifier)\&. Similarly,
\fBsd_bus_creds_get_ppid()\fR
will retrieve the parent PID\&. Note that PID 1 has no parent process, in which case \-ENXIO is returned\&.
.PP
\fBsd_bus_creds_get_pidfd_dup()\fR
will retrieve the PID file descriptor (pidfd), see
\fBpidfd_open\fR(2)
for details\&. The file descriptor is duplicated and thus must be closed by the caller\&.
.PP
\fBsd_bus_creds_get_tid()\fR
will retrieve the TID (thread identifier)\&.
.PP
\fBsd_bus_creds_get_uid()\fR
will retrieve the numeric UID (user identifier)\&. Similarly,
\fBsd_bus_creds_get_euid()\fR
returns the effective UID,
\fBsd_bus_creds_get_suid()\fR
the saved UID and
\fBsd_bus_creds_get_fsuid()\fR
the file system UID\&.
.PP
\fBsd_bus_creds_get_gid()\fR
will retrieve the numeric GID (group identifier)\&. Similarly,
\fBsd_bus_creds_get_egid()\fR
returns the effective GID,
\fBsd_bus_creds_get_sgid()\fR
the saved GID and
\fBsd_bus_creds_get_fsgid()\fR
the file system GID\&.
.PP
\fBsd_bus_creds_get_supplementary_gids()\fR
will retrieve the supplementary GIDs list\&.
.PP
\fBsd_bus_creds_get_comm()\fR
will retrieve the comm field (truncated name of the executable, as stored in
/proc/\fIpid\fR/comm)\&.
.PP
\fBsd_bus_creds_get_tid_comm()\fR
will retrieve the comm field of the thread (as stored in
/proc/\fIpid\fR/task/\fItid\fR/comm)\&.
.PP
\fBsd_bus_creds_get_exe()\fR
will retrieve the path to the program executable (as stored in the
/proc/\fIpid\fR/exe
link, but with the
" (deleted)"
suffix removed)\&. Note that kernel threads do not have an executable path, in which case \-ENXIO is returned\&. Note that this property should not be used for more than explanatory information, in particular it should not be used for security\-relevant decisions\&. That\*(Aqs because the executable might have been replaced or removed by the time the value can be processed\&. Moreover, the kernel exports this information in an ambiguous way (i\&.e\&. a deleted executable cannot be safely distinguished from one whose name suffix is
" (deleted)")\&.
.PP
\fBsd_bus_creds_get_cmdline()\fR
will retrieve an array of command line arguments (as stored in
/proc/\fIpid\fR/cmdline)\&. Note that kernel threads do not have a command line, in which case \-ENXIO is returned\&.
.PP
\fBsd_bus_creds_get_cgroup()\fR
will retrieve the control group path\&. See
\m[blue]\fBControl Groups v2\fR\m[]\&\s-2\u[1]\d\s+2\&.
.PP
\fBsd_bus_creds_get_unit()\fR
will retrieve the systemd unit name (in the system instance of systemd) that the process is a part of\&. See
\fBsystemd.unit\fR(5)\&. For processes that are not part of a unit, returns \-ENXIO\&.
.PP
\fBsd_bus_creds_get_user_unit()\fR
will retrieve the systemd unit name (in the user instance of systemd) that the process is a part of\&. See
\fBsystemd.unit\fR(5)\&. For processes that are not part of a user unit, returns \-ENXIO\&.
.PP
\fBsd_bus_creds_get_slice()\fR
will retrieve the systemd slice (a unit in the system instance of systemd) that the process is a part of\&. See
\fBsystemd.slice\fR(5)\&. Similarly,
\fBsd_bus_creds_get_user_slice()\fR
retrieves the systemd slice of the process, in the user instance of systemd\&.
.PP
\fBsd_bus_creds_get_session()\fR
will retrieve the identifier of the login session that the process is a part of\&. Please note the login session may be limited to a stub process or two\&. User processes may instead be started from their systemd user manager, e\&.g\&. GUI applications started using DBus activation, as well as service processes which are shared between multiple logins of the same user\&. For processes that are not part of a session, returns \-ENXIO\&.
.PP
\fBsd_bus_creds_get_owner_uid()\fR
will retrieve the numeric UID (user identifier) of the user who owns the user unit or login session that the process is a part of\&. See
\fBsystemd-logind.service\fR(8)\&. For processes that are not part of a user unit or session, returns \-ENXIO\&.
.PP
\fBsd_bus_creds_has_effective_cap()\fR
will check whether the capability specified by
\fIcapability\fR
was set in the effective capabilities mask\&. A positive return value means that it was set, zero means that it was not set, and a negative return value indicates an error\&. See
\fBcapabilities\fR(7)
and the
\fIAmbientCapabilities=\fR
and
\fICapabilityBoundingSet=\fR
settings in
\fBsystemd.exec\fR(5)\&.
.PP
\fBsd_bus_creds_has_permitted_cap()\fR
is similar to
\fBsd_bus_creds_has_effective_cap()\fR, but will check the permitted capabilities mask\&.
.PP
\fBsd_bus_creds_has_inheritable_cap()\fR
is similar to
\fBsd_bus_creds_has_effective_cap()\fR, but will check the inheritable capabilities mask\&.
.PP
\fBsd_bus_creds_has_bounding_cap()\fR
is similar to
\fBsd_bus_creds_has_effective_cap()\fR, but will check the bounding capabilities mask\&.
.PP
\fBsd_bus_creds_get_selinux_context()\fR
will retrieve the SELinux security context (label) of the process\&.
.PP
\fBsd_bus_creds_get_audit_session_id()\fR
will retrieve the audit session identifier of the process\&. Returns \-ENXIO for processes that are not part of an audit session\&.
.PP
\fBsd_bus_creds_get_audit_login_uid()\fR
will retrieve the audit user login identifier (the identifier of the user who is "responsible" for the session)\&. Returns \-ENXIO for processes that are not part of an audit session\&.
.PP
\fBsd_bus_creds_get_tty()\fR
will retrieve the controlling TTY, without the prefixing "/dev/"\&. Returns \-ENXIO for processes that have no controlling TTY\&.
.PP
\fBsd_bus_creds_get_unique_name()\fR
will retrieve the D\-Bus unique name\&. See
\m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
.PP
\fBsd_bus_creds_get_well_known_names()\fR
will retrieve the set of D\-Bus well\-known names\&. See
\m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2\&.
.PP
\fBsd_bus_creds_get_description()\fR
will retrieve a descriptive name of the bus connection of the peer\&. This name is useful to discern multiple bus connections by the same peer, and may be altered by the peer with the
\fBsd_bus_set_description\fR(3)
call\&.
.PP
All functions that take a
\fIconst char**\fR
parameter will store the answer there as an address of a
\fBNUL\fR\-terminated string\&. It will be valid as long as
\fIc\fR
remains valid, and should not be freed or modified by the caller\&.
.PP
All functions that take a
\fIchar***\fR
parameter will store the answer there as an address of an array of strings\&. Each individual string is
\fBNUL\fR\-terminated, and the array is
\fBNULL\fR\-terminated as a whole\&. It will be valid as long as
\fIc\fR
remains valid, and should not be freed or modified by the caller\&.
.SH "RETURN VALUE"
.PP
On success, these calls return 0 or a positive integer\&. On failure, these calls return a negative errno\-style error code\&.
.SS "Errors"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-ENODATA\fR
.RS 4
The given field is not available in the credentials object
\fIc\fR\&.
.RE
.PP
\fB\-ENXIO\fR
.RS 4
The given field is not specified for the described process or peer\&. This will be returned by
\fBsd_bus_creds_get_unit()\fR,
\fBsd_bus_creds_get_slice()\fR,
\fBsd_bus_creds_get_user_unit()\fR,
\fBsd_bus_creds_get_user_slice()\fR, and
\fBsd_bus_creds_get_session()\fR
if the process is not part of a systemd system unit, systemd user unit, systemd slice, or logind session\&. It will be returned by
\fBsd_bus_creds_get_owner_uid()\fR
if the process is not part of a systemd user unit or logind session\&. It will also be returned by
\fBsd_bus_creds_get_exe()\fR
and
\fBsd_bus_creds_get_cmdline()\fR
for kernel threads (since these are not started from an executable binary, nor have a command line), and by
\fBsd_bus_creds_get_audit_session_id()\fR
and
\fBsd_bus_creds_get_audit_login_uid()\fR
when the process is not part of an audit session, and
\fBsd_bus_creds_get_tty()\fR
if the process has no controlling TTY\&.
.RE
.PP
\fB\-EINVAL\fR
.RS 4
Specified pointer parameter is
\fBNULL\fR\&.
.RE
.PP
\fB\-ENOMEM\fR
.RS 4
Memory allocation failed\&.
.RE
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.PP
The code described here uses
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "HISTORY"
.PP
\fBsd_bus_creds_get_pid()\fR,
\fBsd_bus_creds_get_tid()\fR,
\fBsd_bus_creds_get_gid()\fR,
\fBsd_bus_creds_get_comm()\fR,
\fBsd_bus_creds_get_tid_comm()\fR,
\fBsd_bus_creds_get_exe()\fR,
\fBsd_bus_creds_get_cmdline()\fR,
\fBsd_bus_creds_get_cgroup()\fR,
\fBsd_bus_creds_get_unit()\fR,
\fBsd_bus_creds_get_user_unit()\fR,
\fBsd_bus_creds_get_slice()\fR,
\fBsd_bus_creds_get_session()\fR,
\fBsd_bus_creds_get_owner_uid()\fR,
\fBsd_bus_creds_has_effective_cap()\fR,
\fBsd_bus_creds_has_permitted_cap()\fR,
\fBsd_bus_creds_has_inheritable_cap()\fR,
\fBsd_bus_creds_has_bounding_cap()\fR,
\fBsd_bus_creds_get_selinux_context()\fR,
\fBsd_bus_creds_get_audit_session_id()\fR,
\fBsd_bus_creds_get_audit_login_uid()\fR,
\fBsd_bus_creds_get_unique_name()\fR,
\fBsd_bus_creds_get_well_known_names()\fR,
\fBsd_bus_creds_get_ppid()\fR,
\fBsd_bus_creds_get_uid()\fR,
\fBsd_bus_creds_get_euid()\fR,
\fBsd_bus_creds_get_suid()\fR,
\fBsd_bus_creds_get_fsuid()\fR,
\fBsd_bus_creds_get_egid()\fR,
\fBsd_bus_creds_get_sgid()\fR,
\fBsd_bus_creds_get_fsgid()\fR,
\fBsd_bus_creds_get_supplementary_gids()\fR,
\fBsd_bus_creds_get_tty()\fR,
\fBsd_bus_creds_get_description()\fR, and
\fBsd_bus_creds_get_user_slice()\fR
were added in version 221\&.
.PP
\fBsd_bus_creds_get_pidfd_dup()\fR
was added in version 256\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_creds_new_from_pid\fR(2), \fBfork\fR(2), \fBexecve\fR(2), \fBcredentials\fR(7), \fBfree\fR(3), \fBproc\fR(5), \fBsystemd.journal-fields\fR(7)
.SH "NOTES"
.IP " 1." 4
Control Groups v2
.RS 4
\%https://docs.kernel.org/admin-guide/cgroup-v2.html
.RE
.IP " 2." 4
The D-Bus specification
.RS 4
\%https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus
.RE