1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="sd_pid_get_owner_uid" conditional='HAVE_PAM'
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>sd_pid_get_owner_uid</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>sd_pid_get_owner_uid</refentrytitle>
16    <manvolnum>3</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>sd_pid_get_owner_uid</refname>
21    <refname>sd_pid_get_session</refname>
22    <refname>sd_pid_get_user_unit</refname>
23    <refname>sd_pid_get_unit</refname>
24    <refname>sd_pid_get_machine_name</refname>
25    <refname>sd_pid_get_slice</refname>
26    <refname>sd_pid_get_user_slice</refname>
27    <refname>sd_pid_get_cgroup</refname>
28    <refname>sd_peer_get_owner_uid</refname>
29    <refname>sd_peer_get_session</refname>
30    <refname>sd_peer_get_user_unit</refname>
31    <refname>sd_peer_get_unit</refname>
32    <refname>sd_peer_get_machine_name</refname>
33    <refname>sd_peer_get_slice</refname>
34    <refname>sd_peer_get_user_slice</refname>
35    <refname>sd_peer_get_cgroup</refname>
36    <refpurpose>Determine the owner uid of the user unit or session,
37    or the session, user unit, system unit, container/VM or slice that
38    a specific PID or socket peer belongs to</refpurpose>
39  </refnamediv>
40
41  <refsynopsisdiv>
42    <funcsynopsis>
43      <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
44
45      <funcprototype>
46        <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
47        <paramdef>pid_t <parameter>pid</parameter></paramdef>
48        <paramdef>uid_t *<parameter>uid</parameter></paramdef>
49      </funcprototype>
50
51      <funcprototype>
52        <funcdef>int <function>sd_pid_get_session</function></funcdef>
53        <paramdef>pid_t <parameter>pid</parameter></paramdef>
54        <paramdef>char **<parameter>session</parameter></paramdef>
55      </funcprototype>
56
57      <funcprototype>
58        <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
59        <paramdef>pid_t <parameter>pid</parameter></paramdef>
60        <paramdef>char **<parameter>unit</parameter></paramdef>
61      </funcprototype>
62
63      <funcprototype>
64        <funcdef>int <function>sd_pid_get_unit</function></funcdef>
65        <paramdef>pid_t <parameter>pid</parameter></paramdef>
66        <paramdef>char **<parameter>unit</parameter></paramdef>
67      </funcprototype>
68
69      <funcprototype>
70        <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
71        <paramdef>pid_t <parameter>pid</parameter></paramdef>
72        <paramdef>char **<parameter>name</parameter></paramdef>
73      </funcprototype>
74
75      <funcprototype>
76        <funcdef>int <function>sd_pid_get_slice</function></funcdef>
77        <paramdef>pid_t <parameter>pid</parameter></paramdef>
78        <paramdef>char **<parameter>slice</parameter></paramdef>
79      </funcprototype>
80
81      <funcprototype>
82        <funcdef>int <function>sd_pid_get_user_slice</function></funcdef>
83        <paramdef>pid_t <parameter>pid</parameter></paramdef>
84        <paramdef>char **<parameter>slice</parameter></paramdef>
85      </funcprototype>
86
87      <funcprototype>
88        <funcdef>int <function>sd_pid_get_cgroup</function></funcdef>
89        <paramdef>pid_t <parameter>pid</parameter></paramdef>
90        <paramdef>char **<parameter>cgroup</parameter></paramdef>
91      </funcprototype>
92
93      <funcprototype>
94        <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>
95        <paramdef>int <parameter>fd</parameter></paramdef>
96        <paramdef>uid_t *<parameter>uid</parameter></paramdef>
97      </funcprototype>
98
99      <funcprototype>
100        <funcdef>int <function>sd_peer_get_session</function></funcdef>
101        <paramdef>int <parameter>fd</parameter></paramdef>
102        <paramdef>char **<parameter>session</parameter></paramdef>
103      </funcprototype>
104
105      <funcprototype>
106        <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
107        <paramdef>int <parameter>fd</parameter></paramdef>
108        <paramdef>char **<parameter>unit</parameter></paramdef>
109      </funcprototype>
110
111      <funcprototype>
112        <funcdef>int <function>sd_peer_get_unit</function></funcdef>
113        <paramdef>int <parameter>fd</parameter></paramdef>
114        <paramdef>char **<parameter>unit</parameter></paramdef>
115      </funcprototype>
116
117      <funcprototype>
118        <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
119        <paramdef>int <parameter>fd</parameter></paramdef>
120        <paramdef>char **<parameter>name</parameter></paramdef>
121      </funcprototype>
122
123      <funcprototype>
124        <funcdef>int <function>sd_peer_get_slice</function></funcdef>
125        <paramdef>int <parameter>fd</parameter></paramdef>
126        <paramdef>char **<parameter>slice</parameter></paramdef>
127      </funcprototype>
128
129      <funcprototype>
130        <funcdef>int <function>sd_peer_get_user_slice</function></funcdef>
131        <paramdef>int <parameter>fd</parameter></paramdef>
132        <paramdef>char **<parameter>slice</parameter></paramdef>
133      </funcprototype>
134
135      <funcprototype>
136        <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
137        <paramdef>int <parameter>fd</parameter></paramdef>
138        <paramdef>char **<parameter>cgroup</parameter></paramdef>
139      </funcprototype>
140    </funcsynopsis>
141  </refsynopsisdiv>
142
143  <refsect1>
144    <title>Description</title>
145
146    <para><function>sd_pid_get_owner_uid()</function> may be used to
147    determine the Unix UID (user identifier) which owns the login
148    session or systemd user unit of a process identified by the
149    specified PID. For processes which are not part of a login session
150    and not managed by a user manager, this function will fail with
151    <constant>-ENODATA</constant>.</para>
152
153    <para><function>sd_pid_get_session()</function> may be used to
154    determine the login session identifier of a process identified by
155    the specified process identifier. The session identifier is a
156    short string, suitable for usage in file system paths. Please
157    note the login session may be limited to a stub process or two.
158    User processes may instead be started from their systemd user
159    manager, e.g. GUI applications started using DBus activation, as
160    well as service processes which are shared between multiple logins
161    of the same user. For processes which are not part of a login
162    session, this function will fail with <constant>-ENODATA</constant>.
163    The returned string needs to be freed with the libc <citerefentry
164    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
165    call after use.</para>
166
167    <para><function>sd_pid_get_user_unit()</function> may be used to
168    determine the systemd user unit (i.e. user service or scope unit)
169    identifier of a process identified by the specified PID. The
170    unit name is a short string, suitable for usage in file system
171    paths. For processes which are not managed by a user manager, this
172    function will fail with <constant>-ENODATA</constant>. The
173    returned string needs to be freed with the libc <citerefentry
174    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
175    call after use.</para>
176
177    <para><function>sd_pid_get_unit()</function> may be used to
178    determine the systemd system unit (i.e. system service or scope
179    unit) identifier of a process identified by the specified PID. The
180    unit name is a short string, suitable for usage in file system
181    paths.  Note that not all processes are part of a system
182    unit/service. For processes not being part of a systemd system
183    unit, this function will fail with <constant>-ENODATA</constant>.
184    (More specifically, this call will not work for kernel threads.)
185    The returned string needs to be freed with the libc <citerefentry
186    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
187    call after use.</para>
188
189    <para><function>sd_pid_get_machine_name()</function> may be used
190    to determine the name of the VM or container is a member of. The
191    machine name is a short string, suitable for usage in file system
192    paths. The returned string needs to be freed with the libc
193    <citerefentry
194    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
195    call after use. For processes not part of a VM or container, this
196    function fails with <constant>-ENODATA</constant>.</para>
197
198    <para><function>sd_pid_get_slice()</function> may be used to
199    determine the slice unit the process is a member of. See
200    <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
201    for details about slices. The returned string needs to be freed
202    with the libc
203    <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
204    call after use.</para>
205
206    <para>Similarly, <function>sd_pid_get_user_slice()</function>
207    returns the user slice (as managed by the user's systemd instance)
208    of a process.</para>
209
210    <para><function>sd_pid_get_cgroup()</function> returns the control
211    group path of the specified process, relative to the root of the
212    hierarchy. Returns the path without trailing slash, except for
213    processes located in the root control group, where "/" is
214    returned. To find the actual control group path in the file system,
215    the returned path needs to be prefixed with
216    <filename>/sys/fs/cgroup/</filename> (if the unified control group
217    setup is used), or
218    <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
219    (if the legacy multi-hierarchy control group setup is used).</para>
220
221    <para>If the <varname>pid</varname> parameter of any of these
222    functions is passed as 0, the operation is executed for the
223    calling process.</para>
224
225    <para>The <function>sd_peer_get_owner_uid()</function>,
226    <function>sd_peer_get_session()</function>,
227    <function>sd_peer_get_user_unit()</function>,
228    <function>sd_peer_get_unit()</function>,
229    <function>sd_peer_get_machine_name()</function>,
230    <function>sd_peer_get_slice()</function>,
231    <function>sd_peer_get_user_slice()</function> and
232    <function>sd_peer_get_cgroup()</function> calls operate similar to
233    their PID counterparts, but operate on a connected AF_UNIX socket
234    and retrieve information about the connected peer process. Note
235    that these fields are retrieved via <filename>/proc/</filename>,
236    and hence are not suitable for authorization purposes, as they are
237    subject to races.</para>
238  </refsect1>
239
240  <refsect1>
241    <title>Return Value</title>
242
243    <para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative
244    errno-style error code.</para>
245
246    <refsect2>
247      <title>Errors</title>
248
249      <para>Returned errors may indicate the following problems:</para>
250
251      <variablelist>
252
253        <varlistentry>
254          <term><constant>-ESRCH</constant></term>
255
256          <listitem><para>The specified PID does not refer to a running process.</para>
257          </listitem>
258        </varlistentry>
259
260        <varlistentry>
261          <term><constant>-EBADF</constant></term>
262
263          <listitem><para>The specified socket file descriptor was invalid.</para></listitem>
264        </varlistentry>
265
266        <varlistentry>
267          <term><constant>-ENODATA</constant></term>
268
269          <listitem><para>The given field is not specified for the described process or peer.</para>
270          </listitem>
271        </varlistentry>
272
273        <varlistentry>
274          <term><constant>-EINVAL</constant></term>
275
276          <listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, where
277          that is not accepted).</para></listitem>
278        </varlistentry>
279
280        <varlistentry>
281          <term><constant>-ENOMEM</constant></term>
282
283          <listitem><para>Memory allocation failed.</para></listitem>
284        </varlistentry>
285      </variablelist>
286    </refsect2>
287  </refsect1>
288
289  <refsect1>
290    <title>Notes</title>
291
292    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
293
294    <para>Note that the login session identifier as
295    returned by <function>sd_pid_get_session()</function>
296    is completely unrelated to the process session
297    identifier as returned by
298    <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
299  </refsect1>
300
301  <refsect1>
302    <title>See Also</title>
303
304    <para>
305      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
306      <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
307      <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
308      <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
309      <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
310      <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
311    </para>
312  </refsect1>
313
314</refentry>
315