'\" t .TH "SD_BUS_CREDS_GET_PID" "3" "" "elogind 255" "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_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 <elogind/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_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_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 always return \-ENODATA, as elogind can not support systemd units\&. .PP \fBsd_bus_creds_get_user_unit()\fR will always return \-ENODATA, as elogind can not support systemd units\&. .PP \fBsd_bus_creds_get_slice()\fR will retrieve the current session, as this is the same as slices in elogind\&. See \fBsd_bus_creds_get_session()\fR\&. \fBsd_bus_creds_get_user_slice()\fR retrieves the the user session, as this is the same as the user slice in elogind\&. See \fBsd_bus_creds_get_user_session()\fR\&. .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 elogind 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 \fBelogind\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)\&. .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 elogind system unit, elogind user unit, elogind slice, or logind session\&. It will be returned by \fBsd_bus_creds_get_owner_uid()\fR if the process is not part of a elogind 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 \fBlibelogind\fR\ \&\fBpkg-config\fR(8) file\&. .SH "SEE ALSO" .PP \fBelogind\fR(8), \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), \fBelogind.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