sd_pid_get_owner_uid(3) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | HISTORY | SEE ALSO | COLOPHON

SD_PID_GET_OWNER_UID(3)   sd_pid_get_owner_uid   SD_PID_GET_OWNER_UID(3)

NAME         top

       sd_pid_get_owner_uid, sd_pid_get_session, sd_pid_get_user_unit,
       sd_pid_get_unit, sd_pid_get_machine_name, sd_pid_get_slice,
       sd_pid_get_user_slice, sd_pid_get_cgroup, sd_pidfd_get_owner_uid,
       sd_pidfd_get_session, sd_pidfd_get_user_unit, sd_pidfd_get_unit,
       sd_pidfd_get_machine_name, sd_pidfd_get_slice,
       sd_pidfd_get_user_slice, sd_pidfd_get_cgroup,
       sd_peer_get_owner_uid, sd_peer_get_session,
       sd_peer_get_user_unit, sd_peer_get_unit,
       sd_peer_get_machine_name, sd_peer_get_slice,
       sd_peer_get_user_slice, sd_peer_get_cgroup - Determine the owner
       uid of the user unit or session, or the session, user unit,
       system unit, container/VM or slice that a specific PID or socket
       peer belongs to

SYNOPSIS         top

       #include <systemd/sd-login.h>

       int sd_pid_get_owner_uid(pid_t pid, uid_t *uid);

       int sd_pid_get_session(pid_t pid, char **session);

       int sd_pid_get_user_unit(pid_t pid, char **unit);

       int sd_pid_get_unit(pid_t pid, char **unit);

       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_pid_get_cgroup(pid_t pid, char **cgroup);

       int sd_pidfd_get_owner_uid(int pidfd, uid_t *uid);

       int sd_pidfd_get_session(int pidfd, char **session);

       int sd_pidfd_get_user_unit(int pidfd, char **unit);

       int sd_pidfd_get_unit(int pidfd, char **unit);

       int sd_pidfd_get_machine_name(int pidfd, char **name);

       int sd_pidfd_get_slice(int pidfd, char **slice);

       int sd_pidfd_get_user_slice(int pidfd, char **slice);

       int sd_pidfd_get_cgroup(int pidfd, char **cgroup);

       int sd_peer_get_owner_uid(int fd, uid_t *uid);

       int sd_peer_get_session(int fd, char **session);

       int sd_peer_get_user_unit(int fd, char **unit);

       int sd_peer_get_unit(int fd, char **unit);

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

       int sd_peer_get_cgroup(int fd, char **cgroup);

DESCRIPTION         top

       sd_pid_get_owner_uid() may be used to determine the Unix UID
       (user identifier) which owns the login session or systemd user
       unit of a process identified by the specified PID. For processes
       which are not part of a login session and not managed by a user
       manager, this function will fail with -ENODATA.

       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. 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 which are not part of a login session, this function
       will fail with -ENODATA. 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. The unit name is a short string,
       suitable for usage in file system paths. For processes which are
       not managed by a user manager, this function will fail with
       -ENODATA. 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. For processes not
       being part of a systemd system unit, this function will fail with
       -ENODATA. (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_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 container, this function fails
       with -ENODATA.

       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.

       Similarly, sd_pid_get_user_slice() returns the user slice (as
       managed by the user's systemd instance) of a process.

       sd_pid_get_cgroup() returns the control group path of the
       specified process, relative to the root of the hierarchy. Returns
       the path without trailing slash, except for processes located in
       the root control group, where "/" is returned. To find the actual
       control group path in the file system, the returned path needs to
       be prefixed with /sys/fs/cgroup/ (if the unified control group
       setup is used), or /sys/fs/cgroup/HIERARCHY/ (if the legacy
       multi-hierarchy control group setup is used).

       If the pid parameter of any of these functions is passed as 0,
       the operation is executed for the calling process.

       The sd_pidfd_get_owner_uid(), sd_pidfd_get_session(),
       sd_pidfd_get_user_unit(), sd_pidfd_get_unit(),
       sd_pidfd_get_machine_name(), sd_pidfd_get_slice(),
       sd_pidfd_get_user_slice() and sd_pidfd_get_cgroup() calls operate
       similarly to their PID counterparts, but accept a PIDFD instead
       of a PID, which means they are not subject to recycle race
       conditions as the process is pinned by the file descriptor during
       the whole duration of the invocation. Note that these require a
       kernel that supports PIDFD. A suitable file descriptor may be
       acquired via pidfd_open(2).

       The sd_peer_get_owner_uid(), sd_peer_get_session(),
       sd_peer_get_user_unit(), sd_peer_get_unit(),
       sd_peer_get_machine_name(), sd_peer_get_slice(),
       sd_peer_get_user_slice() and sd_peer_get_cgroup() calls operate
       similarly to their PID counterparts, but accept 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         top

       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:

       -ESRCH
           The specified PID does not refer to a running process.

       -EBADF
           The specified socket file descriptor was invalid.

       -ENODATA
           The given field is not specified for the described process or
           peer.

       -EINVAL
           An input parameter was invalid (out of range, or NULL, where
           that is not accepted).

       -ENOMEM
           Memory allocation failed.

NOTES         top

       Functions described here are available as a shared library, which
       can be compiled against 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).

HISTORY         top

       sd_peer_get_cgroup(), sd_peer_get_machine_name(),
       sd_peer_get_owner_uid(), sd_peer_get_session(),
       sd_peer_get_slice(), sd_peer_get_unit(),
       sd_peer_get_user_slice(), sd_peer_get_user_unit(),
       sd_pid_get_cgroup(), sd_pid_get_machine_name(),
       sd_pid_get_owner_uid(), sd_pid_get_session(), sd_pid_get_slice(),
       sd_pid_get_unit(), sd_pid_get_user_slice(), and
       sd_pid_get_user_unit() were added in version 236.

       sd_pidfd_get_owner_uid(), sd_pidfd_get_session(),
       sd_pidfd_get_user_unit(), sd_pidfd_get_unit(),
       sd_pidfd_get_machine_name(), sd_pidfd_get_slice(),
       sd_pidfd_get_user_slice(), and sd_pidfd_get_cgroup() were added
       in version 253.

SEE ALSO         top

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

COLOPHON         top

       This page is part of the systemd (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 2023-12-22.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-12-22.)  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 is not part of the original manual page), send a mail to
       man-pages@man7.org

systemd 255                                      SD_PID_GET_OWNER_UID(3)

Pages that refer to this page: homectl(1)journalctl(1)localectl(1)loginctl(1)machinectl(1)portablectl(1)systemctl(1)systemd(1)systemd-analyze(1)systemd-inhibit(1)systemd-nspawn(1)systemd-vmspawn(1)timedatectl(1)userdbctl(1)sd-login(3)sd_machine_get_class(3)sd_session_is_active(3)sd_uid_get_state(3)systemd.directives(7)systemd.index(7)systemd-tmpfiles(8)