2011-12-19 06:02:17 +04:00
<?xml version='1.0'?> <!-- * - nxml - * -->
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2010 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
2012-04-12 02:20:58 +04:00
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
2011-12-19 06:02:17 +04:00
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2012-04-12 02:20:58 +04:00
Lesser General Public License for more details.
2011-12-19 06:02:17 +04:00
2012-04-12 02:20:58 +04:00
You should have received a copy of the GNU Lesser General Public License
2011-12-19 06:02:17 +04:00
along with systemd; If not, see <http: / / w w w . g n u . o r g / l i c e n s e s /> .
-->
2013-02-03 07:47:47 +04:00
<refentry id= "sd_pid_get_session" conditional= 'HAVE_PAM' >
2011-12-19 06:02:17 +04:00
<refentryinfo >
<title > sd_pid_get_session</title>
<productname > systemd</productname>
<authorgroup >
<author >
<contrib > Developer</contrib>
<firstname > Lennart</firstname>
<surname > Poettering</surname>
<email > lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta >
<refentrytitle > sd_pid_get_session</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_pid_get_session</refname>
2012-01-04 18:35:30 +04:00
<refname > sd_pid_get_unit</refname>
2013-04-15 16:16:45 +04:00
<refname > sd_pid_get_user_unit</refname>
2011-12-19 06:02:17 +04:00
<refname > sd_pid_get_owner_uid</refname>
2013-04-16 06:36:06 +04:00
<refname > sd_pid_get_machine_name</refname>
2013-07-19 20:10:12 +04:00
<refname > sd_pid_get_slice</refname>
<refpurpose > Determine session, service, owner of a
session, container/VM or slice of a specific
PID</refpurpose>
2011-12-19 06:02:17 +04:00
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-login.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int <function > sd_pid_get_session</function> </funcdef>
<paramdef > pid_t <parameter > pid</parameter> </paramdef>
<paramdef > char** <parameter > session</parameter> </paramdef>
</funcprototype>
2012-01-03 23:51:38 +04:00
<funcprototype >
2012-01-04 18:35:30 +04:00
<funcdef > int <function > sd_pid_get_unit</function> </funcdef>
2012-01-03 23:51:38 +04:00
<paramdef > pid_t <parameter > pid</parameter> </paramdef>
2012-01-04 18:35:30 +04:00
<paramdef > char** <parameter > unit</parameter> </paramdef>
2012-01-03 23:51:38 +04:00
</funcprototype>
2013-04-15 16:16:45 +04:00
<funcprototype >
<funcdef > int <function > sd_pid_get_user_unit</function> </funcdef>
<paramdef > pid_t <parameter > pid</parameter> </paramdef>
<paramdef > char** <parameter > unit</parameter> </paramdef>
</funcprototype>
2011-12-19 06:02:17 +04:00
<funcprototype >
<funcdef > int <function > sd_pid_get_owner_uid</function> </funcdef>
<paramdef > pid_t <parameter > pid</parameter> </paramdef>
<paramdef > uid_t* <parameter > uid</parameter> </paramdef>
</funcprototype>
2013-04-16 06:36:06 +04:00
<funcprototype >
<funcdef > int <function > sd_pid_get_machine_name</function> </funcdef>
<paramdef > pid_t <parameter > pid</parameter> </paramdef>
<paramdef > char** <parameter > name</parameter> </paramdef>
</funcprototype>
2013-07-19 20:10:12 +04:00
<funcprototype >
<funcdef > int <function > sd_pid_get_slice</function> </funcdef>
<paramdef > pid_t <parameter > pid</parameter> </paramdef>
<paramdef > char** <parameter > slice</parameter> </paramdef>
</funcprototype>
2011-12-19 06:02:17 +04:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > <function > sd_pid_get_session()</function> may be
used to determine the login session identifier of a
2011-12-19 16:57:07 +04:00
process identified by the specified process
identifier. The session identifier is a short string,
suitable for usage in file system paths. Note that not
all processes are part of a login session (e.g. system
2012-01-03 23:51:38 +04:00
service processes, user processes that are shared
between multiple sessions of the same user, or kernel
threads). For processes not being part of a login
session this function will fail. The returned string
needs to be freed with the libc
<citerefentry > <refentrytitle > free</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
call after use.</para>
2012-01-04 18:35:30 +04:00
<para > <function > sd_pid_get_unit()</function> may be
2013-04-15 16:16:45 +04:00
used to determine the systemd system unit (i.e. system
2012-01-04 18:35:30 +04:00
service) identifier of a process identified by the
2013-04-15 16:16:45 +04:00
specified PID. The unit name is a short string,
suitable for usage in file system paths. Note that not
all processes are part of a system unit/service
2012-01-04 18:35:30 +04:00
(e.g. user processes, or kernel threads). For
2013-04-15 16:16:45 +04:00
processes not being part of a systemd system unit this
function will fail. (More specifically: this call will
not work for processes that are part of user units,
use <function > sd_pid_get_user_unit()</function> for
2013-04-16 06:36:06 +04:00
that.) The returned string needs to be freed with the
2013-04-15 16:16:45 +04:00
libc
2011-12-19 06:02:17 +04:00
<citerefentry > <refentrytitle > free</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
call after use.</para>
2013-04-15 16:16:45 +04:00
<para > <function > sd_pid_get_user_unit()</function> may
be used to determine the systemd user unit (i.e. user
service) identifier of a process identified by the
specified PID. This is similar to
<function > sd_pid_get_unit()</function> but applies to
user units instead of system units.</para>
2011-12-19 06:02:17 +04:00
<para > <function > sd_pid_get_owner_uid()</function> may
be used to determine the Unix user identifier of the
owner of the session of a process identified the
specified PID. Note that this function will succeed
for user processes which are shared between multiple
login sessions of the same user, where
<function > sd_pid_get_session()</function> will
fail. For processes not being part of a login session
and not being a shared process of a user this function
will fail.</para>
2012-02-11 06:45:23 +04:00
2013-07-19 20:10:12 +04:00
<para > <function > sd_pid_get_machine_name()</function>
may be used to determine the name of the VM or
container is a member of. The machine name is a short
string, suitable for usage in file system paths. The
returned string needs to be freed with the libc
<citerefentry > <refentrytitle > free</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
call after use.</para>
<para > <function > sd_pid_get_slice()</function> may be
used to determine the slice unit the process is a
member of. See
<citerefentry > <refentrytitle > systemd.slice</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry>
for details about slices. The returned string needs to
be freed with the libc
2013-04-16 06:36:06 +04:00
<citerefentry > <refentrytitle > free</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry>
call after use.</para>
2013-06-27 03:47:34 +04:00
<para > If the <varname > pid</varname> parameter of any
2013-09-12 23:12:49 +04:00
of these functions is passed as 0, the operation is
2012-02-11 06:45:23 +04:00
executed for the calling process.</para>
2011-12-19 06:02:17 +04:00
</refsect1>
<refsect1 >
<title > Return Value</title>
2013-09-12 23:12:49 +04:00
<para > On success, these calls return 0 or a positive
2011-12-19 06:02:17 +04:00
integer. On failure, these calls return a negative
errno-style error code.</para>
</refsect1>
<refsect1 >
<title > Notes</title>
2012-01-03 23:51:38 +04:00
<para > The <function > sd_pid_get_session()</function> ,
2013-04-15 16:16:45 +04:00
<function > sd_pid_get_unit()</function> ,
2013-04-16 06:36:06 +04:00
<function > sd_pid_get_user_unit()</function> ,
2013-07-19 20:10:12 +04:00
<function > sd_pid_get_owner_uid()</function> ,
<function > sd_pid_get_machine_name()</function> and
<function > sd_pid_get_slice()</function> interfaces are
2013-12-26 05:47:43 +04:00
available as a shared library, which can be compiled and
2013-07-19 20:10:12 +04:00
linked to with the
2014-02-19 21:30:41 +04:00
<constant > libsystemd</constant> <citerefentry > <refentrytitle > pkg-config</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry>
2011-12-19 06:02:17 +04:00
file.</para>
<para > Note that the login session identifier as
returned by <function > sd_pid_get_session()</function>
is completely unrelated to the process session
identifier as returned by
<citerefentry > <refentrytitle > getsid</refentrytitle> <manvolnum > 2</manvolnum> </citerefentry> .</para>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
<citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> ,
2012-07-13 03:50:05 +04:00
<citerefentry > <refentrytitle > sd-login</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2011-12-19 06:02:17 +04:00
<citerefentry > <refentrytitle > sd_session_is_active</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> ,
2013-07-19 20:10:12 +04:00
<citerefentry > <refentrytitle > getsid</refentrytitle> <manvolnum > 2</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > systemd.slice</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry>
2011-12-19 06:02:17 +04:00
</para>
</refsect1>
</refentry>