1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2010 Lennart Poettering
13 <refentry id="sd_pid_get_owner_uid" conditional='HAVE_PAM'
14 xmlns:xi="http://www.w3.org/2001/XInclude">
17 <title>sd_pid_get_owner_uid</title>
18 <productname>systemd</productname>
22 <contrib>Developer</contrib>
23 <firstname>Lennart</firstname>
24 <surname>Poettering</surname>
25 <email>lennart@poettering.net</email>
31 <refentrytitle>sd_pid_get_owner_uid</refentrytitle>
32 <manvolnum>3</manvolnum>
36 <refname>sd_pid_get_owner_uid</refname>
37 <refname>sd_pid_get_session</refname>
38 <refname>sd_pid_get_user_unit</refname>
39 <refname>sd_pid_get_unit</refname>
40 <refname>sd_pid_get_machine_name</refname>
41 <refname>sd_pid_get_slice</refname>
42 <refname>sd_pid_get_user_slice</refname>
43 <refname>sd_pid_get_cgroup</refname>
44 <refname>sd_peer_get_owner_uid</refname>
45 <refname>sd_peer_get_session</refname>
46 <refname>sd_peer_get_user_unit</refname>
47 <refname>sd_peer_get_unit</refname>
48 <refname>sd_peer_get_machine_name</refname>
49 <refname>sd_peer_get_slice</refname>
50 <refname>sd_peer_get_user_slice</refname>
51 <refname>sd_peer_get_cgroup</refname>
52 <refpurpose>Determine the owner uid of the user unit or session,
53 or the session, user unit, system unit, container/VM or slice that
54 a specific PID or socket peer belongs to.</refpurpose>
59 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
62 <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
63 <paramdef>pid_t <parameter>pid</parameter></paramdef>
64 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
68 <funcdef>int <function>sd_pid_get_session</function></funcdef>
69 <paramdef>pid_t <parameter>pid</parameter></paramdef>
70 <paramdef>char **<parameter>session</parameter></paramdef>
74 <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
75 <paramdef>pid_t <parameter>pid</parameter></paramdef>
76 <paramdef>char **<parameter>unit</parameter></paramdef>
80 <funcdef>int <function>sd_pid_get_unit</function></funcdef>
81 <paramdef>pid_t <parameter>pid</parameter></paramdef>
82 <paramdef>char **<parameter>unit</parameter></paramdef>
86 <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
87 <paramdef>pid_t <parameter>pid</parameter></paramdef>
88 <paramdef>char **<parameter>name</parameter></paramdef>
92 <funcdef>int <function>sd_pid_get_slice</function></funcdef>
93 <paramdef>pid_t <parameter>pid</parameter></paramdef>
94 <paramdef>char **<parameter>slice</parameter></paramdef>
98 <funcdef>int <function>sd_pid_get_user_slice</function></funcdef>
99 <paramdef>pid_t <parameter>pid</parameter></paramdef>
100 <paramdef>char **<parameter>slice</parameter></paramdef>
104 <funcdef>int <function>sd_pid_get_cgroup</function></funcdef>
105 <paramdef>pid_t <parameter>pid</parameter></paramdef>
106 <paramdef>char **<parameter>cgroup</parameter></paramdef>
110 <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>
111 <paramdef>int <parameter>fd</parameter></paramdef>
112 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
116 <funcdef>int <function>sd_peer_get_session</function></funcdef>
117 <paramdef>int <parameter>fd</parameter></paramdef>
118 <paramdef>char **<parameter>session</parameter></paramdef>
122 <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
123 <paramdef>int <parameter>fd</parameter></paramdef>
124 <paramdef>char **<parameter>unit</parameter></paramdef>
128 <funcdef>int <function>sd_peer_get_unit</function></funcdef>
129 <paramdef>int <parameter>fd</parameter></paramdef>
130 <paramdef>char **<parameter>unit</parameter></paramdef>
134 <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
135 <paramdef>int <parameter>fd</parameter></paramdef>
136 <paramdef>char **<parameter>name</parameter></paramdef>
140 <funcdef>int <function>sd_peer_get_slice</function></funcdef>
141 <paramdef>int <parameter>fd</parameter></paramdef>
142 <paramdef>char **<parameter>slice</parameter></paramdef>
146 <funcdef>int <function>sd_peer_get_user_slice</function></funcdef>
147 <paramdef>int <parameter>fd</parameter></paramdef>
148 <paramdef>char **<parameter>slice</parameter></paramdef>
152 <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
153 <paramdef>int <parameter>fd</parameter></paramdef>
154 <paramdef>char **<parameter>cgroup</parameter></paramdef>
160 <title>Description</title>
162 <para><function>sd_pid_get_owner_uid()</function> may be used to
163 determine the Unix UID (user identifier) which owns the login
164 session or systemd user unit of a process identified by the
165 specified PID. For processes which are not part of a login session
166 and not managed by a user manager, this function will fail with
167 <constant>-ENODATA</constant>.</para>
169 <para><function>sd_pid_get_session()</function> may be used to
170 determine the login session identifier of a process identified by
171 the specified process identifier. The session identifier is a
172 short string, suitable for usage in file system paths. Please
173 note the login session may be limited to a stub process or two.
174 User processes may instead be started from their systemd user
175 manager, e.g. GUI applications started using DBus activation, as
176 well as service processes which are shared between multiple logins
177 of the same user. For processes which are not part of a login
178 session, this function will fail with <constant>-ENODATA</constant>.
179 The returned string needs to be freed with the libc <citerefentry
180 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
181 call after use.</para>
183 <para><function>sd_pid_get_user_unit()</function> may be used to
184 determine the systemd user unit (i.e. user service or scope unit)
185 identifier of a process identified by the specified PID. The
186 unit name is a short string, suitable for usage in file system
187 paths. For processes which are not managed by a user manager, this
188 function will fail with <constant>-ENODATA</constant>. The
189 returned string needs to be freed with the libc <citerefentry
190 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
191 call after use.</para>
193 <para><function>sd_pid_get_unit()</function> may be used to
194 determine the systemd system unit (i.e. system service or scope
195 unit) identifier of a process identified by the specified PID. The
196 unit name is a short string, suitable for usage in file system
197 paths. Note that not all processes are part of a system
198 unit/service. For processes not being part of a systemd system
199 unit, this function will fail with <constant>-ENODATA</constant>.
200 (More specifically, this call will not work for kernel threads.)
201 The returned string needs to be freed with the libc <citerefentry
202 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
203 call after use.</para>
205 <para><function>sd_pid_get_machine_name()</function> may be used
206 to determine the name of the VM or container is a member of. The
207 machine name is a short string, suitable for usage in file system
208 paths. The returned string needs to be freed with the libc
210 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
211 call after use. For processes not part of a VM or container, this
212 function fails with <constant>-ENODATA</constant>.</para>
214 <para><function>sd_pid_get_slice()</function> may be used to
215 determine the slice unit the process is a member of. See
216 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
217 for details about slices. The returned string needs to be freed
219 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
220 call after use.</para>
222 <para>Similarly, <function>sd_pid_get_user_slice()</function>
223 returns the user slice (as managed by the user's systemd instance)
226 <para><function>sd_pid_get_cgroup()</function> returns the control
227 group path of the specified process, relative to the root of the
228 hierarchy. Returns the path without trailing slash, except for
229 processes located in the root control group, where "/" is
230 returned. To find the actual control group path in the file system,
231 the returned path needs to be prefixed with
232 <filename>/sys/fs/cgroup/</filename> (if the unified control group
234 <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
235 (if the legacy multi-hierarchy control group setup is used).</para>
237 <para>If the <varname>pid</varname> parameter of any of these
238 functions is passed as 0, the operation is executed for the
239 calling process.</para>
241 <para>The <function>sd_peer_get_owner_uid()</function>,
242 <function>sd_peer_get_session()</function>,
243 <function>sd_peer_get_user_unit()</function>,
244 <function>sd_peer_get_unit()</function>,
245 <function>sd_peer_get_machine_name()</function>,
246 <function>sd_peer_get_slice()</function>,
247 <function>sd_peer_get_user_slice()</function> and
248 <function>sd_peer_get_cgroup()</function> calls operate similar to
249 their PID counterparts, but operate on a connected AF_UNIX socket
250 and retrieve information about the connected peer process. Note
251 that these fields are retrieved via <filename>/proc</filename>,
252 and hence are not suitable for authorization purposes, as they are
253 subject to races.</para>
257 <title>Return Value</title>
259 <para>On success, these calls return 0 or a positive integer. On
260 failure, these calls return a negative errno-style error
265 <title>Errors</title>
267 <para>Returned errors may indicate the following problems:</para>
272 <term><constant>-ESRCH</constant></term>
274 <listitem><para>The specified PID does not refer to a running
280 <term><constant>-EBADF</constant></term>
282 <listitem><para>The specified socket file descriptor was
283 invalid.</para></listitem>
287 <term><constant>-ENODATA</constant></term>
289 <listitem><para>The given field is not specified for the described
290 process or peer.</para>
295 <term><constant>-EINVAL</constant></term>
297 <listitem><para>An input parameter was invalid (out of range,
298 or NULL, where that is not accepted).</para></listitem>
302 <term><constant>-ENOMEM</constant></term>
304 <listitem><para>Memory allocation failed.</para></listitem>
312 <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
314 <para>Note that the login session identifier as
315 returned by <function>sd_pid_get_session()</function>
316 is completely unrelated to the process session
317 identifier as returned by
318 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
322 <title>See Also</title>
325 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
326 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
327 <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
328 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
329 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
330 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>