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
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"sd_pid_get_owner_uid" conditional='HAVE_PAM'
>
29 <title>sd_pid_get_owner_uid
</title>
30 <productname>systemd
</productname>
34 <contrib>Developer
</contrib>
35 <firstname>Lennart
</firstname>
36 <surname>Poettering
</surname>
37 <email>lennart@poettering.net
</email>
43 <refentrytitle>sd_pid_get_owner_uid
</refentrytitle>
44 <manvolnum>3</manvolnum>
48 <refname>sd_pid_get_owner_uid
</refname>
49 <refname>sd_pid_get_session
</refname>
50 <refname>sd_pid_get_user_unit
</refname>
51 <refname>sd_pid_get_unit
</refname>
52 <refname>sd_pid_get_machine_name
</refname>
53 <refname>sd_pid_get_slice
</refname>
54 <refname>sd_pid_get_user_slice
</refname>
55 <refname>sd_pid_get_cgroup
</refname>
56 <refname>sd_peer_get_owner_uid
</refname>
57 <refname>sd_peer_get_session
</refname>
58 <refname>sd_peer_get_user_unit
</refname>
59 <refname>sd_peer_get_unit
</refname>
60 <refname>sd_peer_get_machine_name
</refname>
61 <refname>sd_peer_get_slice
</refname>
62 <refname>sd_peer_get_user_slice
</refname>
63 <refname>sd_peer_get_cgroup
</refname>
64 <refpurpose>Determine the owner uid of the user unit or session,
65 or the session, user unit, system unit, container/VM or slice that
66 a specific PID or socket peer belongs to.
</refpurpose>
71 <funcsynopsisinfo>#include
<systemd/sd-login.h
></funcsynopsisinfo>
74 <funcdef>int
<function>sd_pid_get_owner_uid
</function></funcdef>
75 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
76 <paramdef>uid_t *
<parameter>uid
</parameter></paramdef>
80 <funcdef>int
<function>sd_pid_get_session
</function></funcdef>
81 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
82 <paramdef>char **
<parameter>session
</parameter></paramdef>
86 <funcdef>int
<function>sd_pid_get_user_unit
</function></funcdef>
87 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
88 <paramdef>char **
<parameter>unit
</parameter></paramdef>
92 <funcdef>int
<function>sd_pid_get_unit
</function></funcdef>
93 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
94 <paramdef>char **
<parameter>unit
</parameter></paramdef>
98 <funcdef>int
<function>sd_pid_get_machine_name
</function></funcdef>
99 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
100 <paramdef>char **
<parameter>name
</parameter></paramdef>
104 <funcdef>int
<function>sd_pid_get_slice
</function></funcdef>
105 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
106 <paramdef>char **
<parameter>slice
</parameter></paramdef>
110 <funcdef>int
<function>sd_pid_get_user_slice
</function></funcdef>
111 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
112 <paramdef>char **
<parameter>slice
</parameter></paramdef>
116 <funcdef>int
<function>sd_pid_get_cgroup
</function></funcdef>
117 <paramdef>pid_t
<parameter>pid
</parameter></paramdef>
118 <paramdef>char **
<parameter>cgroup
</parameter></paramdef>
122 <funcdef>int
<function>sd_peer_get_owner_uid
</function></funcdef>
123 <paramdef>int
<parameter>fd
</parameter></paramdef>
124 <paramdef>uid_t *
<parameter>uid
</parameter></paramdef>
128 <funcdef>int
<function>sd_peer_get_session
</function></funcdef>
129 <paramdef>int
<parameter>fd
</parameter></paramdef>
130 <paramdef>char **
<parameter>session
</parameter></paramdef>
134 <funcdef>int
<function>sd_peer_get_user_unit
</function></funcdef>
135 <paramdef>int
<parameter>fd
</parameter></paramdef>
136 <paramdef>char **
<parameter>unit
</parameter></paramdef>
140 <funcdef>int
<function>sd_peer_get_unit
</function></funcdef>
141 <paramdef>int
<parameter>fd
</parameter></paramdef>
142 <paramdef>char **
<parameter>unit
</parameter></paramdef>
146 <funcdef>int
<function>sd_peer_get_machine_name
</function></funcdef>
147 <paramdef>int
<parameter>fd
</parameter></paramdef>
148 <paramdef>char **
<parameter>name
</parameter></paramdef>
152 <funcdef>int
<function>sd_peer_get_slice
</function></funcdef>
153 <paramdef>int
<parameter>fd
</parameter></paramdef>
154 <paramdef>char **
<parameter>slice
</parameter></paramdef>
158 <funcdef>int
<function>sd_peer_get_user_slice
</function></funcdef>
159 <paramdef>int
<parameter>fd
</parameter></paramdef>
160 <paramdef>char **
<parameter>slice
</parameter></paramdef>
164 <funcdef>int
<function>sd_peer_get_cgroup
</function></funcdef>
165 <paramdef>int
<parameter>fd
</parameter></paramdef>
166 <paramdef>char **
<parameter>cgroup
</parameter></paramdef>
172 <title>Description
</title>
174 <para><function>sd_pid_get_owner_uid()
</function> may be used to
175 determine the Unix UID (user identifier) which owns the login
176 session or systemd user unit of a process identified by the
177 specified PID. For processes which are not part of a login session
178 and not managed by a user manager, this function will fail with
179 <constant>-ENODATA
</constant>.
</para>
181 <para><function>sd_pid_get_session()
</function> may be used to
182 determine the login session identifier of a process identified by
183 the specified process identifier. The session identifier is a
184 short string, suitable for usage in file system paths. Please
185 note the login session may be limited to a stub process or two.
186 User processes may instead be started from their systemd user
187 manager, e.g. GUI applications started using DBus activation, as
188 well as service processes which are shared between multiple logins
189 of the same user. For processes which are not part of a login
190 session, this function will fail with
<constant>-ENODATA
</constant>.
191 The returned string needs to be freed with the libc
<citerefentry
192 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
193 call after use.
</para>
195 <para><function>sd_pid_get_user_unit()
</function> may be used to
196 determine the systemd user unit (i.e. user service or scope unit)
197 identifier of a process identified by the specified PID. The
198 unit name is a short string, suitable for usage in file system
199 paths. For processes which are not managed by a user manager, this
200 function will fail with
<constant>-ENODATA
</constant>. The
201 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_unit()
</function> may be used to
206 determine the systemd system unit (i.e. system service or scope
207 unit) identifier of a process identified by the specified PID. The
208 unit name is a short string, suitable for usage in file system
209 paths. Note that not all processes are part of a system
210 unit/service. For processes not being part of a systemd system
211 unit, this function will fail with
<constant>-ENODATA
</constant>.
212 (More specifically, this call will not work for kernel threads.)
213 The returned string needs to be freed with the libc
<citerefentry
214 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
215 call after use.
</para>
217 <para><function>sd_pid_get_machine_name()
</function> may be used
218 to determine the name of the VM or container is a member of. The
219 machine name is a short string, suitable for usage in file system
220 paths. The returned string needs to be freed with the libc
222 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
223 call after use. For processes not part of a VM or container, this
224 function fails with
<constant>-ENODATA
</constant>.
</para>
226 <para><function>sd_pid_get_slice()
</function> may be used to
227 determine the slice unit the process is a member of. See
228 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
229 for details about slices. The returned string needs to be freed
231 <citerefentry project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
232 call after use.
</para>
234 <para>Similarly,
<function>sd_pid_get_user_slice()
</function>
235 returns the user slice (as managed by the user's systemd instance)
238 <para><function>sd_pid_get_cgroup()
</function> returns the control
239 group path of the specified process, relative to the root of the
240 hierarchy. Returns the path without trailing slash, except for
241 processes located in the root control group, where
"/" is
242 returned. To find the actual control group path in the file system,
243 the returned path needs to be prefixed with
244 <filename>/sys/fs/cgroup/
</filename> (if the unified control group
246 <filename>/sys/fs/cgroup/
<replaceable>HIERARCHY
</replaceable>/
</filename>
247 (if the legacy multi-hierarchy control group setup is used).
</para>
249 <para>If the
<varname>pid
</varname> parameter of any of these
250 functions is passed as
0, the operation is executed for the
251 calling process.
</para>
253 <para>The
<function>sd_peer_get_owner_uid()
</function>,
254 <function>sd_peer_get_session()
</function>,
255 <function>sd_peer_get_user_unit()
</function>,
256 <function>sd_peer_get_unit()
</function>,
257 <function>sd_peer_get_machine_name()
</function>,
258 <function>sd_peer_get_slice()
</function>,
259 <function>sd_peer_get_user_slice()
</function> and
260 <function>sd_peer_get_cgroup()
</function> calls operate similar to
261 their PID counterparts, but operate on a connected AF_UNIX socket
262 and retrieve information about the connected peer process. Note
263 that these fields are retrieved via
<filename>/proc
</filename>,
264 and hence are not suitable for authorization purposes, as they are
265 subject to races.
</para>
269 <title>Return Value
</title>
271 <para>On success, these calls return
0 or a positive integer. On
272 failure, these calls return a negative errno-style error
277 <title>Errors
</title>
279 <para>Returned errors may indicate the following problems:
</para>
284 <term><constant>-ESRCH
</constant></term>
286 <listitem><para>The specified PID does not refer to a running
292 <term><constant>-EBADF
</constant></term>
294 <listitem><para>The specified socket file descriptor was
295 invalid.
</para></listitem>
299 <term><constant>-ENODATA
</constant></term>
301 <listitem><para>The given field is not specified for the described
302 process or peer.
</para>
307 <term><constant>-EINVAL
</constant></term>
309 <listitem><para>An input parameter was invalid (out of range,
310 or NULL, where that is not accepted).
</para></listitem>
314 <term><constant>-ENOMEM
</constant></term>
316 <listitem><para>Memory allocation failed.
</para></listitem>
324 <para>The
<function>sd_pid_get_session()
</function>,
325 <function>sd_pid_get_unit()
</function>,
326 <function>sd_pid_get_user_unit()
</function>,
327 <function>sd_pid_get_owner_uid()
</function>,
328 <function>sd_pid_get_machine_name()
</function>,
329 <function>sd_pid_get_slice()
</function>,
330 <function>sd_pid_get_user_slice()
</function>,
331 <function>sd_peer_get_session()
</function>,
332 <function>sd_peer_get_unit()
</function>,
333 <function>sd_peer_get_user_unit()
</function>,
334 <function>sd_peer_get_owner_uid()
</function>,
335 <function>sd_peer_get_machine_name()
</function>,
336 <function>sd_peer_get_slice()
</function> and
337 <function>sd_peer_get_user_slice()
</function> interfaces are
338 available as a shared library, which can be compiled and linked to
339 with the
<constant>libsystemd
</constant> <citerefentry
340 project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
343 <para>Note that the login session identifier as
344 returned by
<function>sd_pid_get_session()
</function>
345 is completely unrelated to the process session
346 identifier as returned by
347 <citerefentry><refentrytitle>getsid
</refentrytitle><manvolnum>2</manvolnum></citerefentry>.
</para>
351 <title>See Also
</title>
354 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
355 <citerefentry><refentrytitle>sd-login
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
356 <citerefentry><refentrytitle>sd_session_is_active
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
357 <citerefentry><refentrytitle>getsid
</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
358 <citerefentry><refentrytitle>systemd.slice
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>