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