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