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