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