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. The
 152     returned string needs to be freed with the libc
 153     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 154     call after use.</para>
 155
 156     <para><function>sd_pid_get_unit()</function> may be used to
 157     determine the systemd system unit (i.e. system service) identifier
 158     of a process identified by the specified PID. The unit name is a
 159     short string, suitable for usage in file system paths. Note that
 160     not all processes are part of a system unit/service (e.g. user
 161     processes, or kernel threads). For processes not being part of a
 162     systemd system unit this function will fail. (More specifically:
 163     this call will not work for processes that are part of user units,
 164     use <function>sd_pid_get_user_unit()</function> for that.) The
 165     returned string needs to be freed with the libc
 166     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 167     call after use.</para>
 168
 169     <para><function>sd_pid_get_user_unit()</function> may be used to
 170     determine the systemd user unit (i.e. user service) identifier of
 171     a process identified by the specified PID. This is similar to
 172     <function>sd_pid_get_unit()</function> but applies to user units
 173     instead of system units.</para>
 174
 175     <para><function>sd_pid_get_owner_uid()</function> may be used to
 176     determine the Unix user identifier of the owner of the session of
 177     a process identified the specified PID. Note that this function
 178     will succeed for user processes which are shared between multiple
 179     login sessions of the same user, where
 180     <function>sd_pid_get_session()</function> will fail. For processes
 181     not being part of a login session and not being a shared process
 182     of a user this function will fail.</para>
 183
 184     <para><function>sd_pid_get_machine_name()</function> may be used
 185     to determine the name of the VM or container is a member of. The
 186     machine name is a short string, suitable for usage in file system
 187     paths. The returned string needs to be freed with the libc
 188     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     call after use.</para>
 190
 191     <para><function>sd_pid_get_slice()</function> may be used to
 192     determine the slice unit the process is a member of. See
 193     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 194     for details about slices. The returned string needs to be freed
 195     with the libc
 196     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 197     call after use.</para>
 198
 199     <para>If the <varname>pid</varname> parameter of any of these
 200     functions is passed as 0, the operation is executed for the
 201     calling process.</para>
 202
 203     <para>The <function>sd_peer_get_session()</function>,
 204     <function>sd_peer_get_unit()</function>,
 205     <function>sd_peer_get_user_unit()</function>,
 206     <function>sd_peer_get_owner_uid()</function>,
 207     <function>sd_peer_get_machine_name()</function> and
 208     <function>sd_peer_get_slice()</function> calls operate similar to
 209     their PID counterparts, but operate on a connected AF_UNIX socket
 210     and retrieve information about the connected peer process.</para>
 211   </refsect1>
 212
 213   <refsect1>
 214     <title>Return Value</title>
 215
 216     <para>On success, these calls return 0 or a positive integer. On
 217     failure, these calls return a negative errno-style error
 218     code.</para>
 219   </refsect1>
 220
 221   <refsect1>
 222     <title>Notes</title>
 223
 224     <para>The <function>sd_pid_get_session()</function>,
 225     <function>sd_pid_get_unit()</function>,
 226     <function>sd_pid_get_user_unit()</function>,
 227     <function>sd_pid_get_owner_uid()</function>,
 228     <function>sd_pid_get_machine_name()</function>,
 229     <function>sd_pid_get_slice()</function>,
 230     <function>sd_peer_get_session()</function>,
 231     <function>sd_peer_get_unit()</function>,
 232     <function>sd_peer_get_user_unit()</function>,
 233     <function>sd_peer_get_owner_uid()</function>,
 234     <function>sd_peer_get_machine_name()</function> and
 235     <function>sd_peer_get_slice()</function> interfaces are
 236     available as a shared library, which can be compiled
 237     and linked to with the
 238     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 239     file.</para>
 240
 241     <para>Note that the login session identifier as
 242     returned by <function>sd_pid_get_session()</function>
 243     is completely unrelated to the process session
 244     identifier as returned by
 245     <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
 246   </refsect1>
 247
 248   <refsect1>
 249     <title>See Also</title>
 250
 251     <para>
 252       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 253       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 256       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 257       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 258     </para>
 259   </refsect1>
 260
 261 </refentry>