man/sd_bus_creds_new_from_pid.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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_bus_creds_new_from_pid" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_bus_creds_new_from_pid</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_bus_creds_new_from_pid</refname>
  20     <refname>sd_bus_creds_get_mask</refname>
  21     <refname>sd_bus_creds_get_augmented_mask</refname>
  22     <refname>sd_bus_creds_ref</refname>
  23     <refname>sd_bus_creds_unref</refname>
  24     <refname>sd_bus_creds_unrefp</refname>
  25
  26     <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
  27   </refnamediv>
  28
  29   <refsynopsisdiv>
  30     <funcsynopsis>
  31       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  32
  33       <funcprototype>
  34         <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
  35         <paramdef>pid_t <parameter>pid</parameter></paramdef>
  36         <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
  37         <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
  42         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  43       </funcprototype>
  44
  45       <funcprototype>
  46         <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
  47         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
  52         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
  57         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
  62         <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
  63       </funcprototype>
  64     </funcsynopsis>
  65
  66     <para>
  67       <constant>SD_BUS_CREDS_PID</constant>,
  68       <constant>SD_BUS_CREDS_PPID</constant>,
  69       <constant>SD_BUS_CREDS_TID</constant>,
  70       <constant>SD_BUS_CREDS_UID</constant>,
  71       <constant>SD_BUS_CREDS_EUID</constant>,
  72       <constant>SD_BUS_CREDS_SUID</constant>,
  73       <constant>SD_BUS_CREDS_FSUID</constant>,
  74       <constant>SD_BUS_CREDS_GID</constant>,
  75       <constant>SD_BUS_CREDS_EGID</constant>,
  76       <constant>SD_BUS_CREDS_SGID</constant>,
  77       <constant>SD_BUS_CREDS_FSGID</constant>,
  78       <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
  79       <constant>SD_BUS_CREDS_COMM</constant>,
  80       <constant>SD_BUS_CREDS_TID_COMM</constant>,
  81       <constant>SD_BUS_CREDS_EXE</constant>,
  82       <constant>SD_BUS_CREDS_CMDLINE</constant>,
  83       <constant>SD_BUS_CREDS_CGROUP</constant>,
  84       <constant>SD_BUS_CREDS_UNIT</constant>,
  85       <constant>SD_BUS_CREDS_SLICE</constant>,
  86       <constant>SD_BUS_CREDS_USER_UNIT</constant>,
  87       <constant>SD_BUS_CREDS_USER_SLICE</constant>,
  88       <constant>SD_BUS_CREDS_SESSION</constant>,
  89       <constant>SD_BUS_CREDS_OWNER_UID</constant>,
  90       <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
  91       <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
  92       <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
  93       <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
  94       <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
  95       <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
  96       <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
  97       <constant>SD_BUS_CREDS_TTY</constant>,
  98       <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
  99       <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
 100       <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
 101       <constant>SD_BUS_CREDS_AUGMENT</constant>,
 102       <constant>_SD_BUS_CREDS_ALL</constant>
 103     </para>
 104   </refsynopsisdiv>
 105
 106   <refsect1>
 107     <title>Description</title>
 108
 109     <para><function>sd_bus_creds_new_from_pid()</function> creates a
 110     new credentials object and fills it with information about the
 111     process <parameter>pid</parameter>. The pointer to this object
 112     will be stored in the <parameter>ret</parameter> pointer. Note that
 113     credential objects may also be created and retrieved via
 114     <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 115     <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 116     and
 117     <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 118
 119     <para>The information that will be stored is determined by
 120     <parameter>creds_mask</parameter>. It may contain a subset of ORed
 121     constants <constant>SD_BUS_CREDS_PID</constant>,
 122     <constant>SD_BUS_CREDS_PPID</constant>,
 123     <constant>SD_BUS_CREDS_TID</constant>,
 124     <constant>SD_BUS_CREDS_UID</constant>,
 125     <constant>SD_BUS_CREDS_EUID</constant>,
 126     <constant>SD_BUS_CREDS_SUID</constant>,
 127     <constant>SD_BUS_CREDS_FSUID</constant>,
 128     <constant>SD_BUS_CREDS_GID</constant>,
 129     <constant>SD_BUS_CREDS_EGID</constant>,
 130     <constant>SD_BUS_CREDS_SGID</constant>,
 131     <constant>SD_BUS_CREDS_FSGID</constant>,
 132     <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
 133     <constant>SD_BUS_CREDS_COMM</constant>,
 134     <constant>SD_BUS_CREDS_TID_COMM</constant>,
 135     <constant>SD_BUS_CREDS_EXE</constant>,
 136     <constant>SD_BUS_CREDS_CMDLINE</constant>,
 137     <constant>SD_BUS_CREDS_CGROUP</constant>,
 138     <constant>SD_BUS_CREDS_UNIT</constant>,
 139     <constant>SD_BUS_CREDS_SLICE</constant>,
 140     <constant>SD_BUS_CREDS_USER_UNIT</constant>,
 141     <constant>SD_BUS_CREDS_USER_SLICE</constant>,
 142     <constant>SD_BUS_CREDS_SESSION</constant>,
 143     <constant>SD_BUS_CREDS_OWNER_UID</constant>,
 144     <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
 145     <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
 146     <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
 147     <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
 148     <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
 149     <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
 150     <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
 151     <constant>SD_BUS_CREDS_TTY</constant>,
 152     <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
 153     <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
 154     <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
 155     value <constant>_SD_BUS_CREDS_ALL</constant> to request all
 156     supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
 157     constant may not be ORed into the mask for invocations of
 158     <function>sd_bus_creds_new_from_pid()</function>.</para>
 159
 160     <para>Fields can be retrieved from the credentials object using
 161     <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 162     and other functions which correspond directly to the constants
 163     listed above.</para>
 164
 165     <para>A mask of fields which were actually successfully retrieved
 166     can be retrieved with
 167     <function>sd_bus_creds_get_mask()</function>. If the credentials
 168     object was created with
 169     <function>sd_bus_creds_new_from_pid()</function>, this will be a
 170     subset of fields requested in <parameter>creds_mask</parameter>.
 171     </para>
 172
 173     <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
 174     function <function>sd_bus_creds_get_augmented_mask()</function>
 175     returns a bitmask of field constants. The mask indicates which
 176     credential fields have been retrieved in a non-atomic fashion. For
 177     credential objects created via
 178     <function>sd_bus_creds_new_from_pid()</function>, this mask will be
 179     identical to the mask returned by
 180     <function>sd_bus_creds_get_mask()</function>. However, for
 181     credential objects retrieved via
 182     <function>sd_bus_get_name_creds()</function>, this mask will be set
 183     for the credential fields that could not be determined atomically
 184     at peer connection time, and which were later added by reading
 185     augmenting credential data from
 186     <filename>/proc/</filename>. Similarly, for credential objects
 187     retrieved via <function>sd_bus_get_owner_creds()</function>, the
 188     mask is set for the fields that could not be determined atomically
 189     at bus creation time, but have been augmented. Similarly, for
 190     credential objects retrieved via
 191     <function>sd_bus_message_get_creds()</function>, the mask is set
 192     for the fields that could not be determined atomically at message
 193     sending time, but have been augmented. The mask returned by
 194     <function>sd_bus_creds_get_augmented_mask()</function> is always a
 195     subset of (or identical to) the mask returned by
 196     <function>sd_bus_creds_get_mask()</function> for the same
 197     object. The latter call hence returns all credential fields
 198     available in the credential object, the former then marks the
 199     subset of those that have been augmented. Note that augmented
 200     fields are unsuitable for authorization decisions, as they may be
 201     retrieved at different times, thus being subject to races. Hence,
 202     augmented fields should be used exclusively for informational
 203     purposes.
 204     </para>
 205
 206     <para><function>sd_bus_creds_ref()</function> creates a new
 207     reference to the credentials object <parameter>c</parameter>. This
 208     object will not be destroyed until
 209     <function>sd_bus_creds_unref()</function> has been called as many
 210     times plus once more. Once the reference count has dropped to zero,
 211     <parameter>c</parameter> cannot be used anymore, so further
 212     calls to <function>sd_bus_creds_ref(c)</function> or
 213     <function>sd_bus_creds_unref(c)</function> are illegal.</para>
 214
 215     <para><function>sd_bus_creds_unref()</function> destroys a reference
 216     to <parameter>c</parameter>.</para>
 217
 218     <para><function>sd_bus_creds_unrefp()</function> is similar to
 219     <function>sd_bus_creds_unref()</function> but takes a pointer to a
 220     pointer to an <type>sd_bus_creds</type> object. This call is useful in
 221     conjunction with GCC's and LLVM's <ulink
 222     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 223     Variable Attribute</ulink>. Note that this function is defined as
 224     inline function.</para>
 225
 226     <para><function>sd_bus_creds_ref()</function>,
 227     <function>sd_bus_creds_unref()</function> and
 228     <function>sd_bus_creds_unrefp()</function> execute no operation if
 229     the passed in bus credentials object is
 230     <constant>NULL</constant>.</para>
 231
 232   </refsect1>
 233
 234   <refsect1>
 235     <title>Return Value</title>
 236
 237     <para>On success, <function>sd_bus_creds_new_from_pid()</function>
 238     returns 0 or a positive integer. On failure, it returns a negative
 239     errno-style error code.</para>
 240
 241     <para><function>sd_bus_creds_get_mask()</function> returns the
 242     mask of successfully acquired fields.</para>
 243
 244     <para><function>sd_bus_creds_get_augmented_mask()</function>
 245     returns the mask of fields that have been augmented from data in
 246     <filename>/proc/</filename>, and are thus not suitable for
 247     authorization decisions.</para>
 248
 249     <para><function>sd_bus_creds_ref()</function> always returns the
 250     argument.</para>
 251
 252     <para><function>sd_bus_creds_unref()</function> always returns
 253     <constant>NULL</constant>.</para>
 254   </refsect1>
 255
 256   <refsect1>
 257     <title>Reference ownership</title>
 258
 259     <para>Function <function>sd_bus_creds_new_from_pid()</function>
 260     creates a new object and the caller owns the sole reference. When
 261     not needed anymore, this reference should be destroyed with
 262     <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 263     </para>
 264
 265     <refsect2>
 266       <title>Errors</title>
 267
 268       <para>Returned errors may indicate the following problems:</para>
 269
 270       <variablelist>
 271
 272         <varlistentry>
 273           <term><constant>-ESRCH</constant></term>
 274
 275           <listitem><para>Specified <parameter>pid</parameter> could not be found.</para></listitem>
 276         </varlistentry>
 277
 278         <varlistentry>
 279           <term><constant>-EINVAL</constant></term>
 280
 281           <listitem><para>Specified parameter is invalid (<constant>NULL</constant> in case of output
 282           parameters).</para></listitem>
 283         </varlistentry>
 284
 285         <varlistentry>
 286           <term><constant>-ENOMEM</constant></term>
 287
 288           <listitem><para>Memory allocation failed.</para></listitem>
 289         </varlistentry>
 290
 291         <varlistentry>
 292           <term><constant>-EOPNOTSUPP</constant></term>
 293
 294           <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
 295         </varlistentry>
 296       </variablelist>
 297     </refsect2>
 298   </refsect1>
 299
 300   <xi:include href="libsystemd-pkgconfig.xml" />
 301
 302   <refsect1>
 303     <title>History</title>
 304     <para><function>sd_bus_creds_new_from_pid()</function>,
 305     <function>sd_bus_creds_get_mask()</function>,
 306     <function>sd_bus_creds_ref()</function>, and
 307     <function>sd_bus_creds_unref()</function> were added in version 209.</para>
 308     <para><function>sd_bus_creds_get_augmented_mask()</function> was added in version 223.</para>
 309     <para><function>sd_bus_creds_unrefp()</function> was added in version 229.</para>
 310   </refsect1>
 311
 312   <refsect1>
 313     <title>See Also</title>
 314
 315     <para>
 316       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 317       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 318       <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 319       <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 320       <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 321       <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 322     </para>
 323   </refsect1>
 324
 325 </refentry>