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