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