SD_PID_GET_SESSION(3)

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).

SEE ALSO

systemd(1), sd-login(3), sd_session_is_active(3), getsid(2), systemd.slice(5), systemd-machined.service(8)