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