<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="sd_pid_get_session" conditional='HAVE_PAM'>

<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>

<refname>sd_pid_get_unit</refname>

<refname>sd_pid_get_user_unit</refname>

<refname>sd_pid_get_owner_uid</refname>

<refname>sd_pid_get_machine_name</refname>

<refname>sd_pid_get_slice</refname>

<refname>sd_pid_get_user_slice</refname>

<refname>sd_pid_get_cgroup</refname>

<refname>sd_peer_get_session</refname>

<refname>sd_peer_get_unit</refname>

<refname>sd_peer_get_user_unit</refname>

<refname>sd_peer_get_owner_uid</refname>

<refname>sd_peer_get_machine_name</refname>

<refname>sd_peer_get_slice</refname>

<refname>sd_peer_get_user_slice</refname>

<refname>sd_peer_get_cgroup</refname>

<refpurpose>Determine session, unit, owner of a session,

container/VM or slice of a specific PID or socket

peer</refpurpose>

</refnamediv>

<refsynopsisdiv>

<funcsynopsis>

<funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</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>

<funcprototype>

<funcdef>int <function>sd_pid_get_unit</function></funcdef>

<paramdef>pid_t <parameter>pid</parameter></paramdef>

<paramdef>char **<parameter>unit</parameter></paramdef>

</funcprototype>

<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>

<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>

<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>

<funcprototype>

<funcdef>int <function>sd_pid_get_slice</function></funcdef>

<paramdef>pid_t <parameter>pid</parameter></paramdef>

<paramdef>char **<parameter>slice</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_pid_get_user_slice</function></funcdef>

<paramdef>pid_t <parameter>pid</parameter></paramdef>

<paramdef>char **<parameter>slice</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_pid_get_cgroup</function></funcdef>

<paramdef>pid_t <parameter>pid</parameter></paramdef>

<paramdef>char **<parameter>cgroup</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_session</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>session</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_unit</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>unit</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_user_unit</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>unit</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>uid_t *<parameter>uid</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_machine_name</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>name</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_slice</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>slice</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_user_slice</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>slice</parameter></paramdef>

</funcprototype>

<funcprototype>

<funcdef>int <function>sd_peer_get_cgroup</function></funcdef>

<paramdef>int <parameter>fd</parameter></paramdef>

<paramdef>char **<parameter>cgroup</parameter></paramdef>

</funcprototype>

</funcsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><function>sd_pid_get_session()</function> may be used to

determine the login session identifier of a 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 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 with

-ENODATA. The returned string needs to be freed with the libc

<citerefentry

project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use.</para>

<para><function>sd_pid_get_unit()</function> may be used to

determine the systemd system unit (i.e. system service or scope

unit) identifier of a process identified by the 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 (e.g. user processes, or kernel threads). For

processes not being part of a systemd system unit, this function

will fail with -ENODATA. (More specifically, this call will not

work for kernel threads.) The returned string needs to be freed

with the libc <citerefentry

project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use.</para>

<para><function>sd_pid_get_user_unit()</function> may be used to

determine the systemd user unit (i.e. user service or scope unit)

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>

<para><function>sd_pid_get_owner_uid()</function> may be used to

determine the Unix UID (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 with -ENODATA.</para>

<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

project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use. For processes not part of a VM or containers, this

function fails with -ENODATA.</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

<citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call after use.</para>

<para>Similar, <function>sd_pid_get_user_slice()</function>

returns the user slice (as managed by the user's systemd instance)

of a process.</para>

<para><function>sd_pid_get_cgroup()</function> returns the control

group path of the specified process, relative to the root of the

hierarchy. Returns the path without trailing slash, except for

processes located in the root control group, where "/" is

returned. To find the actual control group path in the file system,

the returned path needs to be prefixed with

<filename>/sys/fs/cgroup/</filename> (if the unified control group

setup is used), or

<filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>

(if the legacy multi-hierarchy control group setup is used).</para>

<para>If the <varname>pid</varname> parameter of any of these

functions is passed as 0, the operation is executed for the

calling process.</para>

<para>The <function>sd_peer_get_session()</function>,

<function>sd_peer_get_unit()</function>,

<function>sd_peer_get_user_unit()</function>,

<function>sd_peer_get_owner_uid()</function>,

<function>sd_peer_get_machine_name()</function>,

<function>sd_peer_get_slice()</function>,

<function>sd_peer_get_user_slice()</function> and

<function>sd_peer_get_cgroup()</function> calls operate similar to

their PID counterparts, but operate on a connected AF_UNIX socket

and retrieve information about the connected peer process. Note

that these fields are retrieved via <filename>/proc</filename>,

and hence are not suitable for authorization purposes, as they are

subject to races.</para>

</refsect1>

<refsect1>

<title>Return Value</title>

<para>On success, these calls return 0 or a positive integer. On

failure, these calls return a negative errno-style error

code.</para>

</refsect1>

<refsect1>

<title>Errors</title>

<para>Returned errors may indicate the following problems:</para>

<variablelist>

<varlistentry>

<term><constant>-ESRCH</constant></term>

<listitem><para>The specified PID does not refer to a running

process.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>-BADF</constant></term>

<listitem><para>The specified socket file descriptor was

invalid.</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-ENODATA</constant></term>

<listitem><para>Given field is not specified for the described

process or peer.</para>

</listitem>

</varlistentry>

<varlistentry>

<term><constant>-EINVAL</constant></term>

<listitem><para>An input parameter was invalid (out of range,

or NULL, where that's not accepted).</para></listitem>

</varlistentry>

<varlistentry>

<term><constant>-ENOMEM</constant></term>

<listitem><para>Memory allocation failed.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Notes</title>

<para>The <function>sd_pid_get_session()</function>,

<function>sd_pid_get_unit()</function>,

<function>sd_pid_get_user_unit()</function>,

<function>sd_pid_get_owner_uid()</function>,

<function>sd_pid_get_machine_name()</function>,

<function>sd_pid_get_slice()</function>,

<function>sd_pid_get_user_slice()</function>,

<function>sd_peer_get_session()</function>,

<function>sd_peer_get_unit()</function>,

<function>sd_peer_get_user_unit()</function>,

<function>sd_peer_get_owner_uid()</function>,

<function>sd_peer_get_machine_name()</function>,

<function>sd_peer_get_slice()</function> and

<function>sd_peer_get_user_slice()</function> interfaces are

available as a shared library, which can be compiled and linked to

with the <constant>libsystemd</constant> <citerefentry

project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>

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>,

<citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

<citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>