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 This file is part of elogind.
8 Copyright 2010 Lennart Poettering
10 elogind is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 elogind is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with elogind; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_pid_get_session" conditional='HAVE_PAM'>
27 <title>sd_pid_get_session</title>
28 <productname>elogind</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_pid_get_session</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_pid_get_session</refname>
47 <refname>sd_pid_get_owner_uid</refname>
48 <refname>sd_pid_get_machine_name</refname>
49 <refname>sd_pid_get_cgroup</refname>
50 <refname>sd_peer_get_session</refname>
51 <refname>sd_peer_get_owner_uid</refname>
52 <refname>sd_peer_get_machine_name</refname>
53 <refname>sd_peer_get_cgroup</refname>
54 <refpurpose>Determine session, unit, owner of a session,
55 container/VM or slice of a specific PID or socket
61 <funcsynopsisinfo>#include <elogind/sd-login.h></funcsynopsisinfo>
64 <funcdef>int <function>sd_pid_get_session</function></funcdef>
65 <paramdef>pid_t <parameter>pid</parameter></paramdef>
66 <paramdef>char **<parameter>session</parameter></paramdef>
70 <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
71 <paramdef>pid_t <parameter>pid</parameter></paramdef>
72 <paramdef>uid_t *<parameter>uid</parameter></paramdef>
76 <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
77 <paramdef>pid_t <parameter>pid</parameter></paramdef>
78 <paramdef>char **<parameter>name</parameter></paramdef>
82 <funcdef>int <function>sd_pid_get_cgroup</function></funcdef>
83 <paramdef>pid_t <parameter>pid</parameter></paramdef>
84 <paramdef>char **<parameter>cgroup</parameter></paramdef>
88 <funcdef>int <function>sd_peer_get_session</function></funcdef>
89 <paramdef>int <parameter>fd</parameter></paramdef>
90 <paramdef>char **<parameter>session</parameter></paramdef>
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>
100 <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
101 <paramdef>int <parameter>fd</parameter></paramdef>
102 <paramdef>char **<parameter>name</parameter></paramdef>
106 <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
107 <paramdef>int <parameter>fd</parameter></paramdef>
108 <paramdef>char **<parameter>cgroup</parameter></paramdef>
114 <title>Description</title>
116 <para><function>sd_pid_get_session()</function> may be used to
117 determine the login session identifier of a process identified by
118 the specified process identifier. The session identifier is a
119 short string, suitable for usage in file system paths. Note that
120 not all processes are part of a login session (e.g. system service
121 processes, user processes that are shared between multiple
122 sessions of the same user, or kernel threads). For processes not
123 being part of a login session, this function will fail with
124 -ENODATA. The returned string needs to be freed with the libc
126 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
127 call after use.</para>
129 <para><function>sd_pid_get_owner_uid()</function> may be used to
130 determine the Unix UID (user identifier) of the owner of the
131 session of a process identified the specified PID. Note that this
132 function will succeed for user processes which are shared between
133 multiple login sessions of the same user, whereas
134 <function>sd_pid_get_session()</function> will fail. For processes
135 not being part of a login session and not being a shared process
136 of a user, this function will fail with -ENODATA.</para>
138 <para><function>sd_pid_get_machine_name()</function> may be used
139 to determine the name of the VM or container is a member of. The
140 machine name is a short string, suitable for usage in file system
141 paths. The returned string needs to be freed with the libc
143 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
144 call after use. For processes not part of a VM or containers, this
145 function fails with -ENODATA.</para>
147 <para><function>sd_pid_get_cgroup()</function> returns the control
148 group path of the specified process, relative to the root of the
149 hierarchy. Returns the path without trailing slash, except for
150 processes located in the root control group, where "/" is
151 returned. To find the actual control group path in the file system,
152 the returned path needs to be prefixed with
153 <filename>/sys/fs/cgroup/</filename> (if the unified control group
155 <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
156 (if the legacy multi-hierarchy control group setup is used).</para>
158 <para>If the <varname>pid</varname> parameter of any of these
159 functions is passed as 0, the operation is executed for the
160 calling process.</para>
162 <para>The <function>sd_peer_get_session()</function>,
163 <function>sd_peer_get_owner_uid()</function>,
164 <function>sd_peer_get_machine_name()</function> and
165 <function>sd_peer_get_cgroup()</function> calls operate similar to
166 their PID counterparts, but operate on a connected AF_UNIX socket
167 and retrieve information about the connected peer process. Note
168 that these fields are retrieved via <filename>/proc</filename>,
169 and hence are not suitable for authorization purposes, as they are
170 subject to races.</para>
174 <title>Return Value</title>
176 <para>On success, these calls return 0 or a positive integer. On
177 failure, these calls return a negative errno-style error
182 <title>Errors</title>
184 <para>Returned errors may indicate the following problems:</para>
189 <term><constant>-ESRCH</constant></term>
191 <listitem><para>The specified PID does not refer to a running
197 <term><constant>-BADF</constant></term>
199 <listitem><para>The specified socket file descriptor was
200 invalid.</para></listitem>
204 <term><constant>-ENODATA</constant></term>
206 <listitem><para>The given field is not specified for the described
207 process or peer.</para>
212 <term><constant>-EINVAL</constant></term>
214 <listitem><para>An input parameter was invalid (out of range,
215 or NULL, where that is not accepted).</para></listitem>
219 <term><constant>-ENOMEM</constant></term>
221 <listitem><para>Memory allocation failed.</para></listitem>
229 <para>The <function>sd_pid_get_session()</function>,
230 <function>sd_pid_get_owner_uid()</function>,
231 <function>sd_pid_get_machine_name()</function>,
232 <function>sd_peer_get_session()</function>,
233 <function>sd_peer_get_owner_uid()</function>,
234 <function>sd_peer_get_machine_name()</function>,
235 available as a shared library, which can be compiled and linked to
236 with the <constant>libelogind</constant> <citerefentry
237 project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
240 <para>Note that the login session identifier as
241 returned by <function>sd_pid_get_session()</function>
242 is completely unrelated to the process session
243 identifier as returned by
244 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
248 <title>See Also</title>
251 <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
253 <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
254 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
255 <citerefentry><refentrytitle>elogind.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
256 <citerefentry><refentrytitle>elogind-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>