1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2010 Lennart Poettering
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id="sd_pid_get_session" conditional='HAVE_PAM'>
30 <title>sd_pid_get_session</title>
31 <productname>systemd</productname>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
44 <refentrytitle>sd_pid_get_session</refentrytitle>
45 <manvolnum>3</manvolnum>
49 <refname>sd_pid_get_session</refname>
50 <refname>sd_pid_get_unit</refname>
51 <refname>sd_pid_get_user_unit</refname>
52 <refname>sd_pid_get_owner_uid</refname>
53 <refname>sd_pid_get_machine_name</refname>
54 <refname>sd_pid_get_slice</refname>
55 <refname>sd_peer_get_session</refname>
56 <refname>sd_peer_get_unit</refname>
57 <refname>sd_peer_get_user_unit</refname>
58 <refname>sd_peer_get_owner_uid</refname>
59 <refname>sd_peer_get_machine_name</refname>
60 <refname>sd_peer_get_slice</refname>
61 <refpurpose>Determine session, service, owner of a
62 session, container/VM or slice of a specific
63 PID or socket peer</refpurpose>
68 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
71 <funcdef>int <function>sd_pid_get_session</function></funcdef>
72 <paramdef>pid_t <parameter>pid</parameter></paramdef>
73 <paramdef>char **<parameter>session</parameter></paramdef>
77 <funcdef>int <function>sd_pid_get_unit</function></funcdef>
78 <paramdef>pid_t <parameter>pid</parameter></paramdef>
79 <paramdef>char **<parameter>unit</parameter></paramdef>
83 <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
84 <paramdef>pid_t <parameter>pid</parameter></paramdef>
85 <paramdef>char **<parameter>unit</parameter></paramdef>
89 <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
90 <paramdef>pid_t <parameter>pid</parameter></paramdef>
91 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
95 <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
96 <paramdef>pid_t <parameter>pid</parameter></paramdef>
97 <paramdef>char **<parameter>name</parameter></paramdef>
101 <funcdef>int <function>sd_pid_get_slice</function></funcdef>
102 <paramdef>pid_t <parameter>pid</parameter></paramdef>
103 <paramdef>char **<parameter>slice</parameter></paramdef>
107 <funcdef>int <function>sd_peer_get_session</function></funcdef>
108 <paramdef>int <parameter>fd</parameter></paramdef>
109 <paramdef>char **<parameter>session</parameter></paramdef>
113 <funcdef>int <function>sd_peer_get_unit</function></funcdef>
114 <paramdef>int <parameter>fd</parameter></paramdef>
115 <paramdef>char **<parameter>unit</parameter></paramdef>
119 <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
120 <paramdef>int <parameter>fd</parameter></paramdef>
121 <paramdef>char **<parameter>unit</parameter></paramdef>
125 <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>
126 <paramdef>int <parameter>fd</parameter></paramdef>
127 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
131 <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
132 <paramdef>int <parameter>fd</parameter></paramdef>
133 <paramdef>char **<parameter>name</parameter></paramdef>
137 <funcdef>int <function>sd_peer_get_slice</function></funcdef>
138 <paramdef>int <parameter>fd</parameter></paramdef>
139 <paramdef>char **<parameter>slice</parameter></paramdef>
145 <title>Description</title>
147 <para><function>sd_pid_get_session()</function> may be used to
148 determine the login session identifier of a process identified by
149 the specified process identifier. The session identifier is a
150 short string, suitable for usage in file system paths. Note that
151 not all processes are part of a login session (e.g. system service
152 processes, user processes that are shared between multiple
153 sessions of the same user, or kernel threads). For processes not
154 being part of a login session this function will fail with
155 -ENXIO. The returned string needs to be freed with the libc
157 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
158 call after use.</para>
160 <para><function>sd_pid_get_unit()</function> may be used to
161 determine the systemd system unit (i.e. system service) identifier
162 of a process identified by the specified PID. The unit name is a
163 short string, suitable for usage in file system paths. Note that
164 not all processes are part of a system unit/service (e.g. user
165 processes, or kernel threads). For processes not being part of a
166 systemd system unit this function will fail with -ENXIO (More
167 specifically: this call will not work for processes that are part
168 of user units, use <function>sd_pid_get_user_unit()</function> for
169 that.) The returned string needs to be freed with the libc
171 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
172 call after use.</para>
174 <para><function>sd_pid_get_user_unit()</function> may be used to
175 determine the systemd user unit (i.e. user service) identifier of
176 a process identified by the specified PID. This is similar to
177 <function>sd_pid_get_unit()</function> but applies to user units
178 instead of system units.</para>
180 <para><function>sd_pid_get_owner_uid()</function> may be used to
181 determine the Unix user identifier of the owner of the session of
182 a process identified the specified PID. Note that this function
183 will succeed for user processes which are shared between multiple
184 login sessions of the same user, where
185 <function>sd_pid_get_session()</function> will fail. For processes
186 not being part of a login session and not being a shared process
187 of a user this function will fail with -ENXIO.</para>
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
194 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
195 call after use. For processes not part of a VM or containers this
196 function fails with -ENXIO.</para>
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
203 <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
204 call after use.</para>
206 <para>If the <varname>pid</varname> parameter of any of these
207 functions is passed as 0, the operation is executed for the
208 calling process.</para>
210 <para>The <function>sd_peer_get_session()</function>,
211 <function>sd_peer_get_unit()</function>,
212 <function>sd_peer_get_user_unit()</function>,
213 <function>sd_peer_get_owner_uid()</function>,
214 <function>sd_peer_get_machine_name()</function> and
215 <function>sd_peer_get_slice()</function> calls operate similar to
216 their PID counterparts, but operate on a connected AF_UNIX socket
217 and retrieve information about the connected peer process.</para>
221 <title>Return Value</title>
223 <para>On success, these calls return 0 or a positive integer. On
224 failure, these calls return a negative errno-style error
229 <title>Errors</title>
231 <para>Returned errors may indicate the following problems:</para>
236 <term><constant>-ENXIO</constant></term>
238 <listitem><para>Given field is not specified for the described
239 process or peer.</para>
244 <term><constant>-ESRCH</constant></term>
246 <listitem><para>The specified PID does not refer to a running
252 <term><constant>-ENOMEM</constant></term>
254 <listitem><para>Memory allocation failed.</para></listitem>
262 <para>The <function>sd_pid_get_session()</function>,
263 <function>sd_pid_get_unit()</function>,
264 <function>sd_pid_get_user_unit()</function>,
265 <function>sd_pid_get_owner_uid()</function>,
266 <function>sd_pid_get_machine_name()</function>,
267 <function>sd_pid_get_slice()</function>,
268 <function>sd_peer_get_session()</function>,
269 <function>sd_peer_get_unit()</function>,
270 <function>sd_peer_get_user_unit()</function>,
271 <function>sd_peer_get_owner_uid()</function>,
272 <function>sd_peer_get_machine_name()</function> and
273 <function>sd_peer_get_slice()</function> interfaces are
274 available as a shared library, which can be compiled
275 and linked to with the
276 <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
279 <para>Note that the login session identifier as
280 returned by <function>sd_pid_get_session()</function>
281 is completely unrelated to the process session
282 identifier as returned by
283 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
287 <title>See Also</title>
290 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
291 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
292 <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
293 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
294 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
295 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>