man/sd_pid_get_owner_uid.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2010 Lennart Poettering
   9 -->
  10
  11 <refentry id="sd_pid_get_owner_uid" conditional='HAVE_PAM'
  12           xmlns:xi="http://www.w3.org/2001/XInclude">
  13
  14   <refentryinfo>
  15     <title>sd_pid_get_owner_uid</title>
  16     <productname>systemd</productname>
  17
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>Lennart</firstname>
  22         <surname>Poettering</surname>
  23         <email>lennart@poettering.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>sd_pid_get_owner_uid</refentrytitle>
  30     <manvolnum>3</manvolnum>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname>sd_pid_get_owner_uid</refname>
  35     <refname>sd_pid_get_session</refname>
  36     <refname>sd_pid_get_user_unit</refname>
  37     <refname>sd_pid_get_unit</refname>
  38     <refname>sd_pid_get_machine_name</refname>
  39     <refname>sd_pid_get_slice</refname>
  40     <refname>sd_pid_get_user_slice</refname>
  41     <refname>sd_pid_get_cgroup</refname>
  42     <refname>sd_peer_get_owner_uid</refname>
  43     <refname>sd_peer_get_session</refname>
  44     <refname>sd_peer_get_user_unit</refname>
  45     <refname>sd_peer_get_unit</refname>
  46     <refname>sd_peer_get_machine_name</refname>
  47     <refname>sd_peer_get_slice</refname>
  48     <refname>sd_peer_get_user_slice</refname>
  49     <refname>sd_peer_get_cgroup</refname>
  50     <refpurpose>Determine the owner uid of the user unit or session,
  51     or the session, user unit, system unit, container/VM or slice that
  52     a specific PID or socket peer belongs to.</refpurpose>
  53   </refnamediv>
  54
  55   <refsynopsisdiv>
  56     <funcsynopsis>
  57       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  58
  59       <funcprototype>
  60         <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
  61         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  62         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>int <function>sd_pid_get_session</function></funcdef>
  67         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  68         <paramdef>char **<parameter>session</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
  73         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  74         <paramdef>char **<parameter>unit</parameter></paramdef>
  75       </funcprototype>
  76
  77       <funcprototype>
  78         <funcdef>int <function>sd_pid_get_unit</function></funcdef>
  79         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  80         <paramdef>char **<parameter>unit</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_pid_get_machine_name</function></funcdef>
  85         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  86         <paramdef>char **<parameter>name</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_pid_get_slice</function></funcdef>
  91         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  92         <paramdef>char **<parameter>slice</parameter></paramdef>
  93       </funcprototype>
  94
  95       <funcprototype>
  96         <funcdef>int <function>sd_pid_get_user_slice</function></funcdef>
  97         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  98         <paramdef>char **<parameter>slice</parameter></paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>int <function>sd_pid_get_cgroup</function></funcdef>
 103         <paramdef>pid_t <parameter>pid</parameter></paramdef>
 104         <paramdef>char **<parameter>cgroup</parameter></paramdef>
 105       </funcprototype>
 106
 107       <funcprototype>
 108         <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>
 109         <paramdef>int <parameter>fd</parameter></paramdef>
 110         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 111       </funcprototype>
 112
 113       <funcprototype>
 114         <funcdef>int <function>sd_peer_get_session</function></funcdef>
 115         <paramdef>int <parameter>fd</parameter></paramdef>
 116         <paramdef>char **<parameter>session</parameter></paramdef>
 117       </funcprototype>
 118
 119       <funcprototype>
 120         <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
 121         <paramdef>int <parameter>fd</parameter></paramdef>
 122         <paramdef>char **<parameter>unit</parameter></paramdef>
 123       </funcprototype>
 124
 125       <funcprototype>
 126         <funcdef>int <function>sd_peer_get_unit</function></funcdef>
 127         <paramdef>int <parameter>fd</parameter></paramdef>
 128         <paramdef>char **<parameter>unit</parameter></paramdef>
 129       </funcprototype>
 130
 131       <funcprototype>
 132         <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
 133         <paramdef>int <parameter>fd</parameter></paramdef>
 134         <paramdef>char **<parameter>name</parameter></paramdef>
 135       </funcprototype>
 136
 137       <funcprototype>
 138         <funcdef>int <function>sd_peer_get_slice</function></funcdef>
 139         <paramdef>int <parameter>fd</parameter></paramdef>
 140         <paramdef>char **<parameter>slice</parameter></paramdef>
 141       </funcprototype>
 142
 143       <funcprototype>
 144         <funcdef>int <function>sd_peer_get_user_slice</function></funcdef>
 145         <paramdef>int <parameter>fd</parameter></paramdef>
 146         <paramdef>char **<parameter>slice</parameter></paramdef>
 147       </funcprototype>
 148
 149       <funcprototype>
 150         <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
 151         <paramdef>int <parameter>fd</parameter></paramdef>
 152         <paramdef>char **<parameter>cgroup</parameter></paramdef>
 153       </funcprototype>
 154     </funcsynopsis>
 155   </refsynopsisdiv>
 156
 157   <refsect1>
 158     <title>Description</title>
 159
 160     <para><function>sd_pid_get_owner_uid()</function> may be used to
 161     determine the Unix UID (user identifier) which owns the login
 162     session or systemd user unit of a process identified by the
 163     specified PID. For processes which are not part of a login session
 164     and not managed by a user manager, this function will fail with
 165     <constant>-ENODATA</constant>.</para>
 166
 167     <para><function>sd_pid_get_session()</function> may be used to
 168     determine the login session identifier of a process identified by
 169     the specified process identifier. The session identifier is a
 170     short string, suitable for usage in file system paths. Please
 171     note the login session may be limited to a stub process or two.
 172     User processes may instead be started from their systemd user
 173     manager, e.g. GUI applications started using DBus activation, as
 174     well as service processes which are shared between multiple logins
 175     of the same user. For processes which are not part of a login
 176     session, this function will fail with <constant>-ENODATA</constant>.
 177     The returned string needs to be freed with the libc <citerefentry
 178     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 179     call after use.</para>
 180
 181     <para><function>sd_pid_get_user_unit()</function> may be used to
 182     determine the systemd user unit (i.e. user service or scope unit)
 183     identifier of a process identified by the specified PID. The
 184     unit name is a short string, suitable for usage in file system
 185     paths. For processes which are not managed by a user manager, this
 186     function will fail with <constant>-ENODATA</constant>. The
 187     returned string needs to be freed with the libc <citerefentry
 188     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     call after use.</para>
 190
 191     <para><function>sd_pid_get_unit()</function> may be used to
 192     determine the systemd system unit (i.e. system service or scope
 193     unit) identifier of a process identified by the specified PID. The
 194     unit name is a short string, suitable for usage in file system
 195     paths.  Note that not all processes are part of a system
 196     unit/service. For processes not being part of a systemd system
 197     unit, this function will fail with <constant>-ENODATA</constant>.
 198     (More specifically, this call will not work for kernel threads.)
 199     The returned string needs to be freed with the libc <citerefentry
 200     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 201     call after use.</para>
 202
 203     <para><function>sd_pid_get_machine_name()</function> may be used
 204     to determine the name of the VM or container is a member of. The
 205     machine name is a short string, suitable for usage in file system
 206     paths. The returned string needs to be freed with the libc
 207     <citerefentry
 208     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 209     call after use. For processes not part of a VM or container, this
 210     function fails with <constant>-ENODATA</constant>.</para>
 211
 212     <para><function>sd_pid_get_slice()</function> may be used to
 213     determine the slice unit the process is a member of. See
 214     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 215     for details about slices. The returned string needs to be freed
 216     with the libc
 217     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 218     call after use.</para>
 219
 220     <para>Similarly, <function>sd_pid_get_user_slice()</function>
 221     returns the user slice (as managed by the user's systemd instance)
 222     of a process.</para>
 223
 224     <para><function>sd_pid_get_cgroup()</function> returns the control
 225     group path of the specified process, relative to the root of the
 226     hierarchy. Returns the path without trailing slash, except for
 227     processes located in the root control group, where "/" is
 228     returned. To find the actual control group path in the file system,
 229     the returned path needs to be prefixed with
 230     <filename>/sys/fs/cgroup/</filename> (if the unified control group
 231     setup is used), or
 232     <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
 233     (if the legacy multi-hierarchy control group setup is used).</para>
 234
 235     <para>If the <varname>pid</varname> parameter of any of these
 236     functions is passed as 0, the operation is executed for the
 237     calling process.</para>
 238
 239     <para>The <function>sd_peer_get_owner_uid()</function>,
 240     <function>sd_peer_get_session()</function>,
 241     <function>sd_peer_get_user_unit()</function>,
 242     <function>sd_peer_get_unit()</function>,
 243     <function>sd_peer_get_machine_name()</function>,
 244     <function>sd_peer_get_slice()</function>,
 245     <function>sd_peer_get_user_slice()</function> and
 246     <function>sd_peer_get_cgroup()</function> calls operate similar to
 247     their PID counterparts, but operate on a connected AF_UNIX socket
 248     and retrieve information about the connected peer process. Note
 249     that these fields are retrieved via <filename>/proc</filename>,
 250     and hence are not suitable for authorization purposes, as they are
 251     subject to races.</para>
 252   </refsect1>
 253
 254   <refsect1>
 255     <title>Return Value</title>
 256
 257     <para>On success, these calls return 0 or a positive integer. On
 258     failure, these calls return a negative errno-style error
 259     code.</para>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>Errors</title>
 264
 265     <para>Returned errors may indicate the following problems:</para>
 266
 267     <variablelist>
 268
 269       <varlistentry>
 270         <term><constant>-ESRCH</constant></term>
 271
 272         <listitem><para>The specified PID does not refer to a running
 273         process.</para>
 274         </listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term><constant>-EBADF</constant></term>
 279
 280         <listitem><para>The specified socket file descriptor was
 281         invalid.</para></listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><constant>-ENODATA</constant></term>
 286
 287         <listitem><para>The given field is not specified for the described
 288         process or peer.</para>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><constant>-EINVAL</constant></term>
 294
 295         <listitem><para>An input parameter was invalid (out of range,
 296         or NULL, where that is not accepted).</para></listitem>
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term><constant>-ENOMEM</constant></term>
 301
 302         <listitem><para>Memory allocation failed.</para></listitem>
 303       </varlistentry>
 304     </variablelist>
 305   </refsect1>
 306
 307   <refsect1>
 308     <title>Notes</title>
 309
 310     <xi:include href="libelogind-pkgconfig.xml" xpointer="pkgconfig-text"/>
 311
 312     <para>Note that the login session identifier as
 313     returned by <function>sd_pid_get_session()</function>
 314     is completely unrelated to the process session
 315     identifier as returned by
 316     <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
 317   </refsect1>
 318
 319   <refsect1>
 320     <title>See Also</title>
 321
 322     <para>
 323       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 324       <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 325       <citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 326       <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 327       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 328       <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 329     </para>
 330   </refsect1>
 331
 332 </refentry>