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