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