sd_pid_get_owner_uid(3)

1SD_PID_GET_OWNER_UID(3)      sd_pid_get_owner_uid      SD_PID_GET_OWNER_UID(3)
2
3
4

NAME

6       sd_pid_get_owner_uid, sd_pid_get_session, sd_pid_get_user_unit,
7       sd_pid_get_unit, sd_pid_get_machine_name, sd_pid_get_slice,
8       sd_pid_get_user_slice, sd_pid_get_cgroup, sd_peer_get_owner_uid,
9       sd_peer_get_session, sd_peer_get_user_unit, sd_peer_get_unit,
10       sd_peer_get_machine_name, sd_peer_get_slice, sd_peer_get_user_slice,
11       sd_peer_get_cgroup - Determine the owner uid of the user unit or
12       session, or the session, user unit, system unit, container/VM or slice
13       that a specific PID or socket peer belongs to
14

SYNOPSIS

16       #include <systemd/sd-login.h>
17
18       int sd_pid_get_owner_uid(pid_t pid, uid_t *uid);
19
20       int sd_pid_get_session(pid_t pid, char **session);
21
22       int sd_pid_get_user_unit(pid_t pid, char **unit);
23
24       int sd_pid_get_unit(pid_t pid, char **unit);
25
26       int sd_pid_get_machine_name(pid_t pid, char **name);
27
28       int sd_pid_get_slice(pid_t pid, char **slice);
29
30       int sd_pid_get_user_slice(pid_t pid, char **slice);
31
32       int sd_pid_get_cgroup(pid_t pid, char **cgroup);
33
34       int sd_peer_get_owner_uid(int fd, uid_t *uid);
35
36       int sd_peer_get_session(int fd, char **session);
37
38       int sd_peer_get_user_unit(int fd, char **unit);
39
40       int sd_peer_get_unit(int fd, char **unit);
41
42       int sd_peer_get_machine_name(int fd, char **name);
43
44       int sd_peer_get_slice(int fd, char **slice);
45
46       int sd_peer_get_user_slice(int fd, char **slice);
47
48       int sd_peer_get_cgroup(int fd, char **cgroup);
49

DESCRIPTION

51       sd_pid_get_owner_uid() may be used to determine the Unix UID (user
52       identifier) which owns the login session or systemd user unit of a
53       process identified by the specified PID. For processes which are not
54       part of a login session and not managed by a user manager, this
55       function will fail with -ENODATA.
56
57       sd_pid_get_session() may be used to determine the login session
58       identifier of a process identified by the specified process identifier.
59       The session identifier is a short string, suitable for usage in file
60       system paths. Please note the login session may be limited to a stub
61       process or two. User processes may instead be started from their
62       systemd user manager, e.g. GUI applications started using DBus
63       activation, as well as service processes which are shared between
64       multiple logins of the same user. For processes which are not part of a
65       login session, this function will fail with -ENODATA. The returned
66       string needs to be freed with the libc free(3) call after use.
67
68       sd_pid_get_user_unit() may be used to determine the systemd user unit
69       (i.e. user service or scope unit) identifier of a process identified by
70       the specified PID. The unit name is a short string, suitable for usage
71       in file system paths. For processes which are not managed by a user
72       manager, this function will fail with -ENODATA. The returned string
73       needs to be freed with the libc free(3) call after use.
74
75       sd_pid_get_unit() may be used to determine the systemd system unit
76       (i.e. system service or scope unit) identifier of a process identified
77       by the specified PID. The unit name is a short string, suitable for
78       usage in file system paths. Note that not all processes are part of a
79       system unit/service. For processes not being part of a systemd system
80       unit, this function will fail with -ENODATA. (More specifically, this
81       call will not work for kernel threads.) The returned string needs to be
82       freed with the libc free(3) call after use.
83
84       sd_pid_get_machine_name() may be used to determine the name of the VM
85       or container is a member of. The machine name is a short string,
86       suitable for usage in file system paths. The returned string needs to
87       be freed with the libc free(3) call after use. For processes not part
88       of a VM or container, this function fails with -ENODATA.
89
90       sd_pid_get_slice() may be used to determine the slice unit the process
91       is a member of. See systemd.slice(5) for details about slices. The
92       returned string needs to be freed with the libc free(3) call after use.
93
94       Similarly, sd_pid_get_user_slice() returns the user slice (as managed
95       by the user's systemd instance) of a process.
96
97       sd_pid_get_cgroup() returns the control group path of the specified
98       process, relative to the root of the hierarchy. Returns the path
99       without trailing slash, except for processes located in the root
100       control group, where "/" is returned. To find the actual control group
101       path in the file system, the returned path needs to be prefixed with
102       /sys/fs/cgroup/ (if the unified control group setup is used), or
103       /sys/fs/cgroup/HIERARCHY/ (if the legacy multi-hierarchy control group
104       setup is used).
105
106       If the pid parameter of any of these functions is passed as 0, the
107       operation is executed for the calling process.
108
109       The sd_peer_get_owner_uid(), sd_peer_get_session(),
110       sd_peer_get_user_unit(), sd_peer_get_unit(),
111       sd_peer_get_machine_name(), sd_peer_get_slice(),
112       sd_peer_get_user_slice() and sd_peer_get_cgroup() calls operate similar
113       to their PID counterparts, but operate on a connected AF_UNIX socket
114       and retrieve information about the connected peer process. Note that
115       these fields are retrieved via /proc/, and hence are not suitable for
116       authorization purposes, as they are subject to races.
117

RETURN VALUE

119       On success, these calls return 0 or a positive integer. On failure,
120       these calls return a negative errno-style error code.
121
122   Errors
123       Returned errors may indicate the following problems:
124
125       -ESRCH
126           The specified PID does not refer to a running process.
127
128       -EBADF
129           The specified socket file descriptor was invalid.
130
131       -ENODATA
132           The given field is not specified for the described process or peer.
133
134       -EINVAL
135           An input parameter was invalid (out of range, or NULL, where that
136           is not accepted).
137
138       -ENOMEM
139           Memory allocation failed.
140

NOTES

142       These APIs are implemented as a shared library, which can be compiled
143       and linked to with the libsystemd pkg-config(1) file.
144
145       Note that the login session identifier as returned by
146       sd_pid_get_session() is completely unrelated to the process session
147       identifier as returned by getsid(2).
148

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO