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