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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
10 systemd 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 systemd 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 systemd; 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>systemd</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_unit</refname>
48 <refname>sd_pid_get_user_unit</refname>
49 <refname>sd_pid_get_owner_uid</refname>
50 <refname>sd_pid_get_machine_name</refname>
51 <refpurpose>Determine session, service, owner of a session or container/VM of a specific PID</refpurpose>
56 <funcsynopsisinfo>#include <systemd/sd-login.h></funcsynopsisinfo>
59 <funcdef>int <function>sd_pid_get_session</function></funcdef>
60 <paramdef>pid_t <parameter>pid</parameter></paramdef>
61 <paramdef>char** <parameter>session</parameter></paramdef>
65 <funcdef>int <function>sd_pid_get_unit</function></funcdef>
66 <paramdef>pid_t <parameter>pid</parameter></paramdef>
67 <paramdef>char** <parameter>unit</parameter></paramdef>
71 <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
72 <paramdef>pid_t <parameter>pid</parameter></paramdef>
73 <paramdef>char** <parameter>unit</parameter></paramdef>
77 <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
78 <paramdef>pid_t <parameter>pid</parameter></paramdef>
79 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
83 <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
84 <paramdef>pid_t <parameter>pid</parameter></paramdef>
85 <paramdef>char** <parameter>name</parameter></paramdef>
91 <title>Description</title>
93 <para><function>sd_pid_get_session()</function> may be
94 used to determine the login session identifier of a
95 process identified by the specified process
96 identifier. The session identifier is a short string,
97 suitable for usage in file system paths. Note that not
98 all processes are part of a login session (e.g. system
99 service processes, user processes that are shared
100 between multiple sessions of the same user, or kernel
101 threads). For processes not being part of a login
102 session this function will fail. The returned string
103 needs to be freed with the libc
104 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
105 call after use.</para>
107 <para><function>sd_pid_get_unit()</function> may be
108 used to determine the systemd system unit (i.e. system
109 service) identifier of a process identified by the
110 specified PID. The unit name is a short string,
111 suitable for usage in file system paths. Note that not
112 all processes are part of a system unit/service
113 (e.g. user processes, or kernel threads). For
114 processes not being part of a systemd system unit this
115 function will fail. (More specifically: this call will
116 not work for processes that are part of user units,
117 use <function>sd_pid_get_user_unit()</function> for
118 that.) The returned string needs to be freed with the
120 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
121 call after use.</para>
123 <para><function>sd_pid_get_user_unit()</function> may
124 be used to determine the systemd user unit (i.e. user
125 service) identifier of a process identified by the
126 specified PID. This is similar to
127 <function>sd_pid_get_unit()</function> but applies to
128 user units instead of system units.</para>
130 <para><function>sd_pid_get_owner_uid()</function> may
131 be used to determine the Unix user identifier of the
132 owner of the session of a process identified the
133 specified PID. Note that this function will succeed
134 for user processes which are shared between multiple
135 login sessions of the same user, where
136 <function>sd_pid_get_session()</function> will
137 fail. For processes not being part of a login session
138 and not being a shared process of a user this function
141 <para><function>sd_pid_machine_name()</function> may
142 be used to determine the name of the VM or container
143 is a member of. The machine name is a short string,
144 suitable for usage in file system paths. The returned
145 string needs to be freed with the libc
146 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
147 call after use.</para>
149 <para>If the <literal>pid</literal> parameter of any
150 of these functions is passed as 0 the operation is
151 executed for the calling process.</para>
155 <title>Return Value</title>
157 <para>On success these calls return 0 or a positive
158 integer. On failure, these calls return a negative
159 errno-style error code.</para>
165 <para>The <function>sd_pid_get_session()</function>,
166 <function>sd_pid_get_unit()</function>,
167 <function>sd_pid_get_user_unit()</function>,
168 <function>sd_pid_get_owner_uid()</function> and
169 <function>sd_pid_get_machine_name()</function>
170 interfaces are available as shared library, which can
171 be compiled and linked to with the
172 <literal>libsystemd-login</literal>
173 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
176 <para>Note that the login session identifier as
177 returned by <function>sd_pid_get_session()</function>
178 is completely unrelated to the process session
179 identifier as returned by
180 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
184 <title>See Also</title>
187 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
188 <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
189 <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
190 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>