man/sd_pid_get_session.xml

   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">
   4
   5 <!--
   6   This file is part of elogind.
   7
   8   Copyright 2010 Lennart Poettering
   9
  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.
  14
  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.
  19
  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/>.
  22 -->
  23
  24 <refentry id="sd_pid_get_session" conditional='HAVE_PAM'>
  25
  26   <refentryinfo>
  27     <title>sd_pid_get_session</title>
  28     <productname>elogind</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_pid_get_session</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  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
  56     peer</refpurpose>
  57   </refnamediv>
  58
  59   <refsynopsisdiv>
  60     <funcsynopsis>
  61       <funcsynopsisinfo>#include &lt;elogind/sd-login.h&gt;</funcsynopsisinfo>
  62
  63       <funcprototype>
  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>
  67       </funcprototype>
  68
  69       <funcprototype>
  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>
  73       </funcprototype>
  74
  75       <funcprototype>
  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>
  79       </funcprototype>
  80
  81       <funcprototype>
  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>
  85       </funcprototype>
  86
  87       <funcprototype>
  88         <funcdef>int <function>sd_peer_get_session</function></funcdef>
  89         <paramdef>int <parameter>fd</parameter></paramdef>
  90         <paramdef>char **<parameter>session</parameter></paramdef>
  91       </funcprototype>
  92
  93       <funcprototype>
  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>
  97       </funcprototype>
  98
  99       <funcprototype>
 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>
 103       </funcprototype>
 104
 105       <funcprototype>
 106         <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
 107         <paramdef>int <parameter>fd</parameter></paramdef>
 108         <paramdef>char **<parameter>cgroup</parameter></paramdef>
 109       </funcprototype>
 110     </funcsynopsis>
 111   </refsynopsisdiv>
 112
 113   <refsect1>
 114     <title>Description</title>
 115
 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
 125     <citerefentry
 126     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 127     call after use.</para>
 128
 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>
 137
 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
 142     <citerefentry
 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>
 146
 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
 154     setup is used), or
 155     <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
 156     (if the legacy multi-hierarchy control group setup is used).</para>
 157
 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>
 161
 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>
 171   </refsect1>
 172
 173   <refsect1>
 174     <title>Return Value</title>
 175
 176     <para>On success, these calls return 0 or a positive integer. On
 177     failure, these calls return a negative errno-style error
 178     code.</para>
 179   </refsect1>
 180
 181   <refsect1>
 182     <title>Errors</title>
 183
 184     <para>Returned errors may indicate the following problems:</para>
 185
 186     <variablelist>
 187
 188       <varlistentry>
 189         <term><constant>-ESRCH</constant></term>
 190
 191         <listitem><para>The specified PID does not refer to a running
 192         process.</para>
 193         </listitem>
 194       </varlistentry>
 195
 196       <varlistentry>
 197         <term><constant>-BADF</constant></term>
 198
 199         <listitem><para>The specified socket file descriptor was
 200         invalid.</para></listitem>
 201       </varlistentry>
 202
 203       <varlistentry>
 204         <term><constant>-ENODATA</constant></term>
 205
 206         <listitem><para>The given field is not specified for the described
 207         process or peer.</para>
 208         </listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><constant>-EINVAL</constant></term>
 213
 214         <listitem><para>An input parameter was invalid (out of range,
 215         or NULL, where that is not accepted).</para></listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><constant>-ENOMEM</constant></term>
 220
 221         <listitem><para>Memory allocation failed.</para></listitem>
 222       </varlistentry>
 223     </variablelist>
 224   </refsect1>
 225
 226   <refsect1>
 227     <title>Notes</title>
 228
 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>
 238     file.</para>
 239
 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>
 245   </refsect1>
 246
 247   <refsect1>
 248     <title>See Also</title>
 249
 250     <para>
 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>
 257     </para>
 258   </refsect1>
 259
 260 </refentry>