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