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