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