man/sd_pid_get_session.xml

   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" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2010 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_pid_get_session" conditional='HAVE_PAM'>
  28
  29   <refentryinfo>
  30     <title>sd_pid_get_session</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_pid_get_session</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_pid_get_session</refname>
  50     <refname>sd_pid_get_unit</refname>
  51     <refname>sd_pid_get_user_unit</refname>
  52     <refname>sd_pid_get_owner_uid</refname>
  53     <refname>sd_pid_get_machine_name</refname>
  54     <refname>sd_pid_get_slice</refname>
  55     <refname>sd_peer_get_session</refname>
  56     <refname>sd_peer_get_unit</refname>
  57     <refname>sd_peer_get_user_unit</refname>
  58     <refname>sd_peer_get_owner_uid</refname>
  59     <refname>sd_peer_get_machine_name</refname>
  60     <refname>sd_peer_get_slice</refname>
  61     <refpurpose>Determine session, service, owner of a
  62     session, container/VM or slice of a specific
  63     PID or socket peer</refpurpose>
  64   </refnamediv>
  65
  66   <refsynopsisdiv>
  67     <funcsynopsis>
  68       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  69
  70       <funcprototype>
  71         <funcdef>int <function>sd_pid_get_session</function></funcdef>
  72         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  73         <paramdef>char **<parameter>session</parameter></paramdef>
  74       </funcprototype>
  75
  76       <funcprototype>
  77         <funcdef>int <function>sd_pid_get_unit</function></funcdef>
  78         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  79         <paramdef>char **<parameter>unit</parameter></paramdef>
  80       </funcprototype>
  81
  82       <funcprototype>
  83         <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
  84         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  85         <paramdef>char **<parameter>unit</parameter></paramdef>
  86       </funcprototype>
  87
  88       <funcprototype>
  89         <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
  90         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  91         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  92       </funcprototype>
  93
  94       <funcprototype>
  95         <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
  96         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  97         <paramdef>char **<parameter>name</parameter></paramdef>
  98       </funcprototype>
  99
 100       <funcprototype>
 101         <funcdef>int <function>sd_pid_get_slice</function></funcdef>
 102         <paramdef>pid_t <parameter>pid</parameter></paramdef>
 103         <paramdef>char **<parameter>slice</parameter></paramdef>
 104       </funcprototype>
 105
 106       <funcprototype>
 107         <funcdef>int <function>sd_peer_get_session</function></funcdef>
 108         <paramdef>int <parameter>fd</parameter></paramdef>
 109         <paramdef>char **<parameter>session</parameter></paramdef>
 110       </funcprototype>
 111
 112       <funcprototype>
 113         <funcdef>int <function>sd_peer_get_unit</function></funcdef>
 114         <paramdef>int <parameter>fd</parameter></paramdef>
 115         <paramdef>char **<parameter>unit</parameter></paramdef>
 116       </funcprototype>
 117
 118       <funcprototype>
 119         <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
 120         <paramdef>int <parameter>fd</parameter></paramdef>
 121         <paramdef>char **<parameter>unit</parameter></paramdef>
 122       </funcprototype>
 123
 124       <funcprototype>
 125         <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>
 126         <paramdef>int <parameter>fd</parameter></paramdef>
 127         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 128       </funcprototype>
 129
 130       <funcprototype>
 131         <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
 132         <paramdef>int <parameter>fd</parameter></paramdef>
 133         <paramdef>char **<parameter>name</parameter></paramdef>
 134       </funcprototype>
 135
 136       <funcprototype>
 137         <funcdef>int <function>sd_peer_get_slice</function></funcdef>
 138         <paramdef>int <parameter>fd</parameter></paramdef>
 139         <paramdef>char **<parameter>slice</parameter></paramdef>
 140       </funcprototype>
 141     </funcsynopsis>
 142   </refsynopsisdiv>
 143
 144   <refsect1>
 145     <title>Description</title>
 146
 147     <para><function>sd_pid_get_session()</function> may be used to
 148     determine the login session identifier of a process identified by
 149     the specified process identifier. The session identifier is a
 150     short string, suitable for usage in file system paths. Note that
 151     not all processes are part of a login session (e.g. system service
 152     processes, user processes that are shared between multiple
 153     sessions of the same user, or kernel threads). For processes not
 154     being part of a login session this function will fail with
 155     -ENXIO. The returned string needs to be freed with the libc
 156     <citerefentry
 157     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 158     call after use.</para>
 159
 160     <para><function>sd_pid_get_unit()</function> may be used to
 161     determine the systemd system unit (i.e. system service) identifier
 162     of a process identified by the specified PID. The unit name is a
 163     short string, suitable for usage in file system paths. Note that
 164     not all processes are part of a system unit/service (e.g. user
 165     processes, or kernel threads). For processes not being part of a
 166     systemd system unit this function will fail with -ENXIO (More
 167     specifically: this call will not work for processes that are part
 168     of user units, use <function>sd_pid_get_user_unit()</function> for
 169     that.) The returned string needs to be freed with the libc
 170     <citerefentry
 171     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 172     call after use.</para>
 173
 174     <para><function>sd_pid_get_user_unit()</function> may be used to
 175     determine the systemd user unit (i.e. user service) identifier of
 176     a process identified by the specified PID. This is similar to
 177     <function>sd_pid_get_unit()</function> but applies to user units
 178     instead of system units.</para>
 179
 180     <para><function>sd_pid_get_owner_uid()</function> may be used to
 181     determine the Unix user identifier of the owner of the session of
 182     a process identified the specified PID. Note that this function
 183     will succeed for user processes which are shared between multiple
 184     login sessions of the same user, where
 185     <function>sd_pid_get_session()</function> will fail. For processes
 186     not being part of a login session and not being a shared process
 187     of a user this function will fail with -ENXIO.</para>
 188
 189     <para><function>sd_pid_get_machine_name()</function> may be used
 190     to determine the name of the VM or container is a member of. The
 191     machine name is a short string, suitable for usage in file system
 192     paths. The returned string needs to be freed with the libc
 193     <citerefentry
 194     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 195     call after use. For processes not part of a VM or containers this
 196     function fails with -ENXIO.</para>
 197
 198     <para><function>sd_pid_get_slice()</function> may be used to
 199     determine the slice unit the process is a member of. See
 200     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 201     for details about slices. The returned string needs to be freed
 202     with the libc
 203     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 204     call after use.</para>
 205
 206     <para>If the <varname>pid</varname> parameter of any of these
 207     functions is passed as 0, the operation is executed for the
 208     calling process.</para>
 209
 210     <para>The <function>sd_peer_get_session()</function>,
 211     <function>sd_peer_get_unit()</function>,
 212     <function>sd_peer_get_user_unit()</function>,
 213     <function>sd_peer_get_owner_uid()</function>,
 214     <function>sd_peer_get_machine_name()</function> and
 215     <function>sd_peer_get_slice()</function> calls operate similar to
 216     their PID counterparts, but operate on a connected AF_UNIX socket
 217     and retrieve information about the connected peer process.</para>
 218   </refsect1>
 219
 220   <refsect1>
 221     <title>Return Value</title>
 222
 223     <para>On success, these calls return 0 or a positive integer. On
 224     failure, these calls return a negative errno-style error
 225     code.</para>
 226   </refsect1>
 227
 228   <refsect1>
 229     <title>Errors</title>
 230
 231     <para>Returned errors may indicate the following problems:</para>
 232
 233     <variablelist>
 234
 235       <varlistentry>
 236         <term><constant>-ENXIO</constant></term>
 237
 238         <listitem><para>Given field is not specified for the described
 239         process or peer.</para>
 240         </listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><constant>-ESRCH</constant></term>
 245
 246         <listitem><para>The specified PID does not refer to a running
 247         process.</para>
 248         </listitem>
 249       </varlistentry>
 250
 251       <varlistentry>
 252         <term><constant>-ENOMEM</constant></term>
 253
 254         <listitem><para>Memory allocation failed.</para></listitem>
 255       </varlistentry>
 256     </variablelist>
 257   </refsect1>
 258
 259   <refsect1>
 260     <title>Notes</title>
 261
 262     <para>The <function>sd_pid_get_session()</function>,
 263     <function>sd_pid_get_unit()</function>,
 264     <function>sd_pid_get_user_unit()</function>,
 265     <function>sd_pid_get_owner_uid()</function>,
 266     <function>sd_pid_get_machine_name()</function>,
 267     <function>sd_pid_get_slice()</function>,
 268     <function>sd_peer_get_session()</function>,
 269     <function>sd_peer_get_unit()</function>,
 270     <function>sd_peer_get_user_unit()</function>,
 271     <function>sd_peer_get_owner_uid()</function>,
 272     <function>sd_peer_get_machine_name()</function> and
 273     <function>sd_peer_get_slice()</function> interfaces are
 274     available as a shared library, which can be compiled
 275     and linked to with the
 276     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 277     file.</para>
 278
 279     <para>Note that the login session identifier as
 280     returned by <function>sd_pid_get_session()</function>
 281     is completely unrelated to the process session
 282     identifier as returned by
 283     <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
 284   </refsect1>
 285
 286   <refsect1>
 287     <title>See Also</title>
 288
 289     <para>
 290       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 291       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 292       <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 293       <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 294       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 295       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 296     </para>
 297   </refsect1>
 298
 299 </refentry>