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                 <refpurpose>Determine session, service, owner of a
  53                 session, container/VM or slice of a specific
  54                 PID</refpurpose>
  55         </refnamediv>
  56
  57         <refsynopsisdiv>
  58                 <funcsynopsis>
  59                         <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  60
  61                         <funcprototype>
  62                                 <funcdef>int <function>sd_pid_get_session</function></funcdef>
  63                                 <paramdef>pid_t <parameter>pid</parameter></paramdef>
  64                                 <paramdef>char** <parameter>session</parameter></paramdef>
  65                         </funcprototype>
  66
  67                         <funcprototype>
  68                                 <funcdef>int <function>sd_pid_get_unit</function></funcdef>
  69                                 <paramdef>pid_t <parameter>pid</parameter></paramdef>
  70                                 <paramdef>char** <parameter>unit</parameter></paramdef>
  71                         </funcprototype>
  72
  73                         <funcprototype>
  74                                 <funcdef>int <function>sd_pid_get_user_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_owner_uid</function></funcdef>
  81                                 <paramdef>pid_t <parameter>pid</parameter></paramdef>
  82                                 <paramdef>uid_t* <parameter>uid</parameter></paramdef>
  83                         </funcprototype>
  84
  85                         <funcprototype>
  86                                 <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
  87                                 <paramdef>pid_t <parameter>pid</parameter></paramdef>
  88                                 <paramdef>char** <parameter>name</parameter></paramdef>
  89                         </funcprototype>
  90
  91                         <funcprototype>
  92                                 <funcdef>int <function>sd_pid_get_slice</function></funcdef>
  93                                 <paramdef>pid_t <parameter>pid</parameter></paramdef>
  94                                 <paramdef>char** <parameter>slice</parameter></paramdef>
  95                         </funcprototype>
  96                 </funcsynopsis>
  97         </refsynopsisdiv>
  98
  99         <refsect1>
 100                 <title>Description</title>
 101
 102                 <para><function>sd_pid_get_session()</function> may be
 103                 used to determine the login session identifier of a
 104                 process identified by the specified process
 105                 identifier. The session identifier is a short string,
 106                 suitable for usage in file system paths. Note that not
 107                 all processes are part of a login session (e.g. system
 108                 service processes, user processes that are shared
 109                 between multiple sessions of the same user, or kernel
 110                 threads). For processes not being part of a login
 111                 session this function will fail. The returned string
 112                 needs to be freed with the libc
 113                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 114                 call after use.</para>
 115
 116                 <para><function>sd_pid_get_unit()</function> may be
 117                 used to determine the systemd system unit (i.e. system
 118                 service) identifier of a process identified by the
 119                 specified PID. The unit name is a short string,
 120                 suitable for usage in file system paths. Note that not
 121                 all processes are part of a system unit/service
 122                 (e.g. user processes, or kernel threads). For
 123                 processes not being part of a systemd system unit this
 124                 function will fail. (More specifically: this call will
 125                 not work for processes that are part of user units,
 126                 use <function>sd_pid_get_user_unit()</function> for
 127                 that.) The returned string needs to be freed with the
 128                 libc
 129                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 130                 call after use.</para>
 131
 132                 <para><function>sd_pid_get_user_unit()</function> may
 133                 be used to determine the systemd user unit (i.e. user
 134                 service) identifier of a process identified by the
 135                 specified PID. This is similar to
 136                 <function>sd_pid_get_unit()</function> but applies to
 137                 user units instead of system units.</para>
 138
 139                 <para><function>sd_pid_get_owner_uid()</function> may
 140                 be used to determine the Unix user identifier of the
 141                 owner of the session of a process identified the
 142                 specified PID. Note that this function will succeed
 143                 for user processes which are shared between multiple
 144                 login sessions of the same user, where
 145                 <function>sd_pid_get_session()</function> will
 146                 fail. For processes not being part of a login session
 147                 and not being a shared process of a user this function
 148                 will fail.</para>
 149
 150                 <para><function>sd_pid_get_machine_name()</function>
 151                 may be used to determine the name of the VM or
 152                 container is a member of. The machine name is a short
 153                 string, suitable for usage in file system paths. The
 154                 returned string needs to be freed with the libc
 155                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 156                 call after use.</para>
 157
 158                 <para><function>sd_pid_get_slice()</function> may be
 159                 used to determine the slice unit the process is a
 160                 member of. See
 161                 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 162                 for details about slices. The returned string needs to
 163                 be freed with the libc
 164                 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 165                 call after use.</para>
 166
 167                 <para>If the <varname>pid</varname> parameter of any
 168                 of these functions is passed as 0, the operation is
 169                 executed for the calling process.</para>
 170         </refsect1>
 171
 172         <refsect1>
 173                 <title>Return Value</title>
 174
 175                 <para>On success, these calls return 0 or a positive
 176                 integer. On failure, these calls return a negative
 177                 errno-style error code.</para>
 178         </refsect1>
 179
 180         <refsect1>
 181                 <title>Notes</title>
 182
 183                 <para>The <function>sd_pid_get_session()</function>,
 184                 <function>sd_pid_get_unit()</function>,
 185                 <function>sd_pid_get_user_unit()</function>,
 186                 <function>sd_pid_get_owner_uid()</function>,
 187                 <function>sd_pid_get_machine_name()</function> and
 188                 <function>sd_pid_get_slice()</function> interfaces are
 189                 available as shared library, which can be compiled and
 190                 linked to with the
 191                 <constant>libsystemd-login</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 192                 file.</para>
 193
 194                 <para>Note that the login session identifier as
 195                 returned by <function>sd_pid_get_session()</function>
 196                 is completely unrelated to the process session
 197                 identifier as returned by
 198                 <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
 199         </refsect1>
 200
 201         <refsect1>
 202                 <title>See Also</title>
 203
 204                 <para>
 205                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 206                         <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 207                         <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 208                         <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 209                         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 210                 </para>
 211         </refsect1>
 212
 213 </refentry>