man/sd_pid_get_owner_uid.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_pid_get_owner_uid" conditional='HAVE_PAM'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>sd_pid_get_owner_uid</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>sd_pid_get_owner_uid</refentrytitle>
  16     <manvolnum>3</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>sd_pid_get_owner_uid</refname>
  21     <refname>sd_pid_get_session</refname>
  22     <refname>sd_pid_get_user_unit</refname>
  23     <refname>sd_pid_get_unit</refname>
  24     <refname>sd_pid_get_machine_name</refname>
  25     <refname>sd_pid_get_slice</refname>
  26     <refname>sd_pid_get_user_slice</refname>
  27     <refname>sd_pid_get_cgroup</refname>
  28     <refname>sd_pidfd_get_owner_uid</refname>
  29     <refname>sd_pidfd_get_session</refname>
  30     <refname>sd_pidfd_get_user_unit</refname>
  31     <refname>sd_pidfd_get_unit</refname>
  32     <refname>sd_pidfd_get_machine_name</refname>
  33     <refname>sd_pidfd_get_slice</refname>
  34     <refname>sd_pidfd_get_user_slice</refname>
  35     <refname>sd_pidfd_get_cgroup</refname>
  36     <refname>sd_peer_get_owner_uid</refname>
  37     <refname>sd_peer_get_session</refname>
  38     <refname>sd_peer_get_user_unit</refname>
  39     <refname>sd_peer_get_unit</refname>
  40     <refname>sd_peer_get_machine_name</refname>
  41     <refname>sd_peer_get_slice</refname>
  42     <refname>sd_peer_get_user_slice</refname>
  43     <refname>sd_peer_get_cgroup</refname>
  44     <refpurpose>Determine the owner uid of the user unit or session,
  45     or the session, user unit, system unit, container/VM or slice that
  46     a specific PID or socket peer belongs to</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <funcsynopsis>
  51       <funcsynopsisinfo>#include &lt;systemd/sd-login.h&gt;</funcsynopsisinfo>
  52
  53       <funcprototype>
  54         <funcdef>int <function>sd_pid_get_owner_uid</function></funcdef>
  55         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  56         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
  57       </funcprototype>
  58
  59       <funcprototype>
  60         <funcdef>int <function>sd_pid_get_session</function></funcdef>
  61         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  62         <paramdef>char **<parameter>session</parameter></paramdef>
  63       </funcprototype>
  64
  65       <funcprototype>
  66         <funcdef>int <function>sd_pid_get_user_unit</function></funcdef>
  67         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  68         <paramdef>char **<parameter>unit</parameter></paramdef>
  69       </funcprototype>
  70
  71       <funcprototype>
  72         <funcdef>int <function>sd_pid_get_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_machine_name</function></funcdef>
  79         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  80         <paramdef>char **<parameter>name</parameter></paramdef>
  81       </funcprototype>
  82
  83       <funcprototype>
  84         <funcdef>int <function>sd_pid_get_slice</function></funcdef>
  85         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  86         <paramdef>char **<parameter>slice</parameter></paramdef>
  87       </funcprototype>
  88
  89       <funcprototype>
  90         <funcdef>int <function>sd_pid_get_user_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_cgroup</function></funcdef>
  97         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  98         <paramdef>char **<parameter>cgroup</parameter></paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>int <function>sd_pidfd_get_owner_uid</function></funcdef>
 103         <paramdef>int <parameter>pidfd</parameter></paramdef>
 104         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 105       </funcprototype>
 106
 107       <funcprototype>
 108         <funcdef>int <function>sd_pidfd_get_session</function></funcdef>
 109         <paramdef>int <parameter>pidfd</parameter></paramdef>
 110         <paramdef>char **<parameter>session</parameter></paramdef>
 111       </funcprototype>
 112
 113       <funcprototype>
 114         <funcdef>int <function>sd_pidfd_get_user_unit</function></funcdef>
 115         <paramdef>int <parameter>pidfd</parameter></paramdef>
 116         <paramdef>char **<parameter>unit</parameter></paramdef>
 117       </funcprototype>
 118
 119       <funcprototype>
 120         <funcdef>int <function>sd_pidfd_get_unit</function></funcdef>
 121         <paramdef>int <parameter>pidfd</parameter></paramdef>
 122         <paramdef>char **<parameter>unit</parameter></paramdef>
 123       </funcprototype>
 124
 125       <funcprototype>
 126         <funcdef>int <function>sd_pidfd_get_machine_name</function></funcdef>
 127         <paramdef>int <parameter>pidfd</parameter></paramdef>
 128         <paramdef>char **<parameter>name</parameter></paramdef>
 129       </funcprototype>
 130
 131       <funcprototype>
 132         <funcdef>int <function>sd_pidfd_get_slice</function></funcdef>
 133         <paramdef>int <parameter>pidfd</parameter></paramdef>
 134         <paramdef>char **<parameter>slice</parameter></paramdef>
 135       </funcprototype>
 136
 137       <funcprototype>
 138         <funcdef>int <function>sd_pidfd_get_user_slice</function></funcdef>
 139         <paramdef>int <parameter>pidfd</parameter></paramdef>
 140         <paramdef>char **<parameter>slice</parameter></paramdef>
 141       </funcprototype>
 142
 143       <funcprototype>
 144         <funcdef>int <function>sd_pidfd_get_cgroup</function></funcdef>
 145         <paramdef>int <parameter>pidfd</parameter></paramdef>
 146         <paramdef>char **<parameter>cgroup</parameter></paramdef>
 147       </funcprototype>
 148
 149       <funcprototype>
 150         <funcdef>int <function>sd_peer_get_owner_uid</function></funcdef>
 151         <paramdef>int <parameter>fd</parameter></paramdef>
 152         <paramdef>uid_t *<parameter>uid</parameter></paramdef>
 153       </funcprototype>
 154
 155       <funcprototype>
 156         <funcdef>int <function>sd_peer_get_session</function></funcdef>
 157         <paramdef>int <parameter>fd</parameter></paramdef>
 158         <paramdef>char **<parameter>session</parameter></paramdef>
 159       </funcprototype>
 160
 161       <funcprototype>
 162         <funcdef>int <function>sd_peer_get_user_unit</function></funcdef>
 163         <paramdef>int <parameter>fd</parameter></paramdef>
 164         <paramdef>char **<parameter>unit</parameter></paramdef>
 165       </funcprototype>
 166
 167       <funcprototype>
 168         <funcdef>int <function>sd_peer_get_unit</function></funcdef>
 169         <paramdef>int <parameter>fd</parameter></paramdef>
 170         <paramdef>char **<parameter>unit</parameter></paramdef>
 171       </funcprototype>
 172
 173       <funcprototype>
 174         <funcdef>int <function>sd_peer_get_machine_name</function></funcdef>
 175         <paramdef>int <parameter>fd</parameter></paramdef>
 176         <paramdef>char **<parameter>name</parameter></paramdef>
 177       </funcprototype>
 178
 179       <funcprototype>
 180         <funcdef>int <function>sd_peer_get_slice</function></funcdef>
 181         <paramdef>int <parameter>fd</parameter></paramdef>
 182         <paramdef>char **<parameter>slice</parameter></paramdef>
 183       </funcprototype>
 184
 185       <funcprototype>
 186         <funcdef>int <function>sd_peer_get_user_slice</function></funcdef>
 187         <paramdef>int <parameter>fd</parameter></paramdef>
 188         <paramdef>char **<parameter>slice</parameter></paramdef>
 189       </funcprototype>
 190
 191       <funcprototype>
 192         <funcdef>int <function>sd_peer_get_cgroup</function></funcdef>
 193         <paramdef>int <parameter>fd</parameter></paramdef>
 194         <paramdef>char **<parameter>cgroup</parameter></paramdef>
 195       </funcprototype>
 196     </funcsynopsis>
 197   </refsynopsisdiv>
 198
 199   <refsect1>
 200     <title>Description</title>
 201
 202     <para><function>sd_pid_get_owner_uid()</function> may be used to
 203     determine the Unix UID (user identifier) which owns the login
 204     session or systemd user unit of a process identified by the
 205     specified PID. For processes which are not part of a login session
 206     and not managed by a user manager, this function will fail with
 207     <constant>-ENODATA</constant>.</para>
 208
 209     <para><function>sd_pid_get_session()</function> may be used to
 210     determine the login session identifier of a process identified by
 211     the specified process identifier. The session identifier is a
 212     short string, suitable for usage in file system paths. Please
 213     note the login session may be limited to a stub process or two.
 214     User processes may instead be started from their systemd user
 215     manager, e.g. GUI applications started using DBus activation, as
 216     well as service processes which are shared between multiple logins
 217     of the same user. For processes which are not part of a login
 218     session, this function will fail with <constant>-ENODATA</constant>.
 219     The returned string needs to be freed with the libc <citerefentry
 220     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 221     call after use.</para>
 222
 223     <para><function>sd_pid_get_user_unit()</function> may be used to
 224     determine the systemd user unit (i.e. user service or scope unit)
 225     identifier of a process identified by the specified PID. The
 226     unit name is a short string, suitable for usage in file system
 227     paths. For processes which are not managed by a user manager, this
 228     function will fail with <constant>-ENODATA</constant>. The
 229     returned string needs to be freed with the libc <citerefentry
 230     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 231     call after use.</para>
 232
 233     <para><function>sd_pid_get_unit()</function> may be used to
 234     determine the systemd system unit (i.e. system service or scope
 235     unit) identifier of a process identified by the specified PID. The
 236     unit name is a short string, suitable for usage in file system
 237     paths.  Note that not all processes are part of a system
 238     unit/service. For processes not being part of a systemd system
 239     unit, this function will fail with <constant>-ENODATA</constant>.
 240     (More specifically, this call will not work for kernel threads.)
 241     The returned string needs to be freed with the libc <citerefentry
 242     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 243     call after use.</para>
 244
 245     <para><function>sd_pid_get_machine_name()</function> may be used
 246     to determine the name of the VM or container is a member of. The
 247     machine name is a short string, suitable for usage in file system
 248     paths. The returned string needs to be freed with the libc
 249     <citerefentry
 250     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 251     call after use. For processes not part of a VM or container, this
 252     function fails with <constant>-ENODATA</constant>.</para>
 253
 254     <para><function>sd_pid_get_slice()</function> may be used to
 255     determine the slice unit the process is a member of. See
 256     <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 257     for details about slices. The returned string needs to be freed
 258     with the libc
 259     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 260     call after use.</para>
 261
 262     <para>Similarly, <function>sd_pid_get_user_slice()</function>
 263     returns the user slice (as managed by the user's systemd instance)
 264     of a process.</para>
 265
 266     <para><function>sd_pid_get_cgroup()</function> returns the control
 267     group path of the specified process, relative to the root of the
 268     hierarchy. Returns the path without trailing slash, except for
 269     processes located in the root control group, where "/" is
 270     returned. To find the actual control group path in the file system,
 271     the returned path needs to be prefixed with
 272     <filename>/sys/fs/cgroup/</filename> (if the unified control group
 273     setup is used), or
 274     <filename>/sys/fs/cgroup/<replaceable>HIERARCHY</replaceable>/</filename>
 275     (if the legacy multi-hierarchy control group setup is used).</para>
 276
 277     <para>If the <varname>pid</varname> parameter of any of these
 278     functions is passed as 0, the operation is executed for the
 279     calling process.</para>
 280
 281     <para>The <function>sd_pidfd_get_owner_uid()</function>,
 282     <function>sd_pidfd_get_session()</function>,
 283     <function>sd_pidfd_get_user_unit()</function>,
 284     <function>sd_pidfd_get_unit()</function>,
 285     <function>sd_pidfd_get_machine_name()</function>,
 286     <function>sd_pidfd_get_slice()</function>,
 287     <function>sd_pidfd_get_user_slice()</function> and
 288     <function>sd_pidfd_get_cgroup()</function> calls operate similarly to their PID counterparts, but accept a
 289     <constant>PIDFD</constant> instead of a <constant>PID</constant>, which means they are not subject to recycle
 290     race conditions as the process is pinned by the file descriptor during the whole duration of the invocation.
 291     Note that these require a kernel that supports <constant>PIDFD</constant>. A suitable file descriptor may be
 292     acquired via
 293     <citerefentry project='man-pages'><refentrytitle>pidfd_open</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
 294
 295     <para>The <function>sd_peer_get_owner_uid()</function>,
 296     <function>sd_peer_get_session()</function>,
 297     <function>sd_peer_get_user_unit()</function>,
 298     <function>sd_peer_get_unit()</function>,
 299     <function>sd_peer_get_machine_name()</function>,
 300     <function>sd_peer_get_slice()</function>,
 301     <function>sd_peer_get_user_slice()</function> and
 302     <function>sd_peer_get_cgroup()</function> calls operate similarly to their PID counterparts, but accept a
 303     connected <constant>AF_UNIX</constant> socket and retrieve information about the connected peer process.
 304     Note that these fields are retrieved via <filename>/proc/</filename>, and hence are not suitable for
 305     authorization purposes, as they are subject to races.</para>
 306   </refsect1>
 307
 308   <refsect1>
 309     <title>Return Value</title>
 310
 311     <para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative
 312     errno-style error code.</para>
 313
 314     <refsect2>
 315       <title>Errors</title>
 316
 317       <para>Returned errors may indicate the following problems:</para>
 318
 319       <variablelist>
 320
 321         <varlistentry>
 322           <term><constant>-ESRCH</constant></term>
 323
 324           <listitem><para>The specified PID does not refer to a running process.</para>
 325           </listitem>
 326         </varlistentry>
 327
 328         <varlistentry>
 329           <term><constant>-EBADF</constant></term>
 330
 331           <listitem><para>The specified socket file descriptor was invalid.</para></listitem>
 332         </varlistentry>
 333
 334         <varlistentry>
 335           <term><constant>-ENODATA</constant></term>
 336
 337           <listitem><para>The given field is not specified for the described process or peer.</para>
 338           </listitem>
 339         </varlistentry>
 340
 341         <varlistentry>
 342           <term><constant>-EINVAL</constant></term>
 343
 344           <listitem><para>An input parameter was invalid (out of range, or <constant>NULL</constant>, where
 345           that is not accepted).</para></listitem>
 346         </varlistentry>
 347
 348         <varlistentry>
 349           <term><constant>-ENOMEM</constant></term>
 350
 351           <listitem><para>Memory allocation failed.</para></listitem>
 352         </varlistentry>
 353       </variablelist>
 354     </refsect2>
 355   </refsect1>
 356
 357   <refsect1>
 358     <title>Notes</title>
 359
 360     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 361
 362     <para>Note that the login session identifier as
 363     returned by <function>sd_pid_get_session()</function>
 364     is completely unrelated to the process session
 365     identifier as returned by
 366     <citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para>
 367   </refsect1>
 368
 369   <refsect1>
 370     <title>History</title>
 371     <para><function>sd_peer_get_cgroup()</function>,
 372     <function>sd_peer_get_machine_name()</function>,
 373     <function>sd_peer_get_owner_uid()</function>,
 374     <function>sd_peer_get_session()</function>,
 375     <function>sd_peer_get_slice()</function>,
 376     <function>sd_peer_get_unit()</function>,
 377     <function>sd_peer_get_user_slice()</function>,
 378     <function>sd_peer_get_user_unit()</function>,
 379     <function>sd_pid_get_cgroup()</function>,
 380     <function>sd_pid_get_machine_name()</function>,
 381     <function>sd_pid_get_owner_uid()</function>,
 382     <function>sd_pid_get_session()</function>,
 383     <function>sd_pid_get_slice()</function>,
 384     <function>sd_pid_get_unit()</function>,
 385     <function>sd_pid_get_user_slice()</function>, and
 386     <function>sd_pid_get_user_unit()</function> were added in version 236.</para>
 387     <para><function>sd_pidfd_get_owner_uid()</function>,
 388     <function>sd_pidfd_get_session()</function>,
 389     <function>sd_pidfd_get_user_unit()</function>,
 390     <function>sd_pidfd_get_unit()</function>,
 391     <function>sd_pidfd_get_machine_name()</function>,
 392     <function>sd_pidfd_get_slice()</function>,
 393     <function>sd_pidfd_get_user_slice()</function>, and
 394     <function>sd_pidfd_get_cgroup()</function> were added in version 253.</para>
 395   </refsect1>
 396
 397   <refsect1>
 398     <title>See Also</title>
 399
 400     <para><simplelist type="inline">
 401       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 402       <member><citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 403       <member><citerefentry><refentrytitle>sd_session_is_active</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 404       <member><citerefentry><refentrytitle>getsid</refentrytitle><manvolnum>2</manvolnum></citerefentry></member>
 405       <member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 406       <member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 407     </simplelist></para>
 408   </refsect1>
 409
 410 </refentry>