Name
sd_pid_get_session, sd_pid_get_unit, sd_pid_get_user_unit, sd_pid_get_owner_uid, sd_pid_get_machine_name, sd_pid_get_slice, sd_pid_get_user_slice, sd_peer_get_session, sd_peer_get_unit, sd_peer_get_user_unit, sd_peer_get_owner_uid, sd_peer_get_machine_name, sd_peer_get_slice, sd_peer_get_user_slice — Determine session, unit, owner of a session,
container/VM or slice of a specific PID or socket
peer
Synopsis
#include <systemd/sd-login.h>
int sd_pid_get_session( | pid_t pid, |
| char **session) ; |
int sd_pid_get_unit( | pid_t pid, |
| char **unit) ; |
int sd_pid_get_user_unit( | pid_t pid, |
| char **unit) ; |
int sd_pid_get_owner_uid( | pid_t pid, |
| uid_t *uid) ; |
int sd_pid_get_machine_name( | pid_t pid, |
| char **name) ; |
int sd_pid_get_slice( | pid_t pid, |
| char **slice) ; |
int sd_pid_get_user_slice( | pid_t pid, |
| char **slice) ; |
int sd_peer_get_session( | int fd, |
| char **session) ; |
int sd_peer_get_unit( | int fd, |
| char **unit) ; |
int sd_peer_get_user_unit( | int fd, |
| char **unit) ; |
int sd_peer_get_owner_uid( | int fd, |
| uid_t *uid) ; |
int sd_peer_get_machine_name( | int fd, |
| char **name) ; |
int sd_peer_get_slice( | int fd, |
| char **slice) ; |
int sd_peer_get_user_slice( | int fd, |
| char **slice) ; |
Description
sd_pid_get_session()
may be used to
determine the login session identifier of a process identified by
the specified process identifier. The session identifier is a
short string, suitable for usage in file system paths. Note that
not all processes are part of a login session (e.g. system service
processes, user processes that are shared between multiple
sessions of the same user, or kernel threads). For processes not
being part of a login session this function will fail with
-ENXIO. The returned string needs to be freed with the libc
free(3)
call after use.
sd_pid_get_unit()
may be used to
determine the systemd system unit (i.e. system service or scope
unit) identifier of a process identified by the specified PID. The
unit name is a short string, suitable for usage in file system
paths. Note that not all processes are part of a system
unit/service (e.g. user processes, or kernel threads). For
processes not being part of a systemd system unit this function
will fail with -ENXIO (More specifically: this call will not work
for kernel threads.) The returned string needs to be freed with
the libc free(3)
call after use.
sd_pid_get_user_unit()
may be used to
determine the systemd user unit (i.e. user service or scope unit)
identifier of a process identified by the specified PID. This is
similar to sd_pid_get_unit()
but applies to
user units instead of system units.
sd_pid_get_owner_uid()
may be used to
determine the Unix UID (user identifier) of the owner of the
session of a process identified the specified PID. Note that this
function will succeed for user processes which are shared between
multiple login sessions of the same user, where
sd_pid_get_session()
will fail. For processes
not being part of a login session and not being a shared process
of a user this function will fail with -ENXIO.
sd_pid_get_machine_name()
may be used
to determine the name of the VM or container is a member of. The
machine name is a short string, suitable for usage in file system
paths. The returned string needs to be freed with the libc
free(3)
call after use. For processes not part of a VM or containers this
function fails with -ENXIO.
sd_pid_get_slice()
may be used to
determine the slice unit the process is a member of. See
systemd.slice(5)
for details about slices. The returned string needs to be freed
with the libc
free(3)
call after use.
Similar, sd_pid_get_user_slice()
returns the user slice (as managed by the user's systemd instance)
of a process.
If the pid
parameter of any of these
functions is passed as 0, the operation is executed for the
calling process.
The sd_peer_get_session()
,
sd_peer_get_unit()
,
sd_peer_get_user_unit()
,
sd_peer_get_owner_uid()
,
sd_peer_get_machine_name()
,
sd_peer_get_slice()
and
sd_peer_get_user_slice()
calls operate
similar to their PID counterparts, but operate on a connected
AF_UNIX socket and retrieve information about the connected peer
process. Note that these fields are retrieved via
/proc
, and hence are not suitable for
authorization purposes, as they are subject to races.
Return Value
On success, these calls return 0 or a positive integer. On
failure, these calls return a negative errno-style error
code.
Errors
Returned errors may indicate the following problems:
-ENXIO
Given field is not specified for the described
process or peer.
-ESRCH
The specified PID does not refer to a running
process.
-ENOMEM
Memory allocation failed.
Notes
The sd_pid_get_session()
,
sd_pid_get_unit()
,
sd_pid_get_user_unit()
,
sd_pid_get_owner_uid()
,
sd_pid_get_machine_name()
,
sd_pid_get_slice()
,
sd_pid_get_user_slice()
,
sd_peer_get_session()
,
sd_peer_get_unit()
,
sd_peer_get_user_unit()
,
sd_peer_get_owner_uid()
,
sd_peer_get_machine_name()
,
sd_peer_get_slice()
and
sd_peer_get_user_slice()
interfaces are
available as a shared library, which can be compiled and linked to
with the libsystemd
pkg-config(1)
file.
Note that the login session identifier as
returned by sd_pid_get_session()
is completely unrelated to the process session
identifier as returned by
getsid(2).