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 systemd.
   7
   8   Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd 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   systemd 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 systemd; 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>systemd</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;systemd/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>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>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_UNIT</constant>,
 112       <constant>SD_BUS_CREDS_SLICE</constant>,
 113       <constant>SD_BUS_CREDS_USER_UNIT</constant>,
 114       <constant>SD_BUS_CREDS_USER_SLICE</constant>,
 115       <constant>SD_BUS_CREDS_SESSION</constant>,
 116       <constant>SD_BUS_CREDS_OWNER_UID</constant>,
 117       <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
 118       <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
 119       <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
 120       <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
 121       <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
 122       <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
 123       <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
 124       <constant>SD_BUS_CREDS_TTY</constant>,
 125       <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
 126       <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
 127       <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
 128       <constant>SD_BUS_CREDS_AUGMENT</constant>,
 129       <constant>_SD_BUS_CREDS_ALL</constant>
 130     </para>
 131   </refsynopsisdiv>
 132
 133   <refsect1>
 134     <title>Description</title>
 135
 136     <para><function>sd_bus_creds_new_from_pid()</function> creates a
 137     new credentials object and fills it with information about the
 138     process <parameter>pid</parameter>. The pointer to this object
 139     will be stored in the <parameter>ret</parameter> pointer. Note that
 140     credential objects may also be created and retrieved via
 141     <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142     <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 143     and
 144     <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 145
 146     <para>The information that will be stored is determined by
 147     <parameter>creds_mask</parameter>. It may contain a subset of ORed
 148     constants <constant>SD_BUS_CREDS_PID</constant>,
 149     <constant>SD_BUS_CREDS_PPID</constant>,
 150     <constant>SD_BUS_CREDS_TID</constant>,
 151     <constant>SD_BUS_CREDS_UID</constant>,
 152     <constant>SD_BUS_CREDS_EUID</constant>,
 153     <constant>SD_BUS_CREDS_SUID</constant>,
 154     <constant>SD_BUS_CREDS_FSUID</constant>,
 155     <constant>SD_BUS_CREDS_GID</constant>,
 156     <constant>SD_BUS_CREDS_EGID</constant>,
 157     <constant>SD_BUS_CREDS_SGID</constant>,
 158     <constant>SD_BUS_CREDS_FSGID</constant>,
 159     <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
 160     <constant>SD_BUS_CREDS_COMM</constant>,
 161     <constant>SD_BUS_CREDS_TID_COMM</constant>,
 162     <constant>SD_BUS_CREDS_EXE</constant>,
 163     <constant>SD_BUS_CREDS_CMDLINE</constant>,
 164     <constant>SD_BUS_CREDS_CGROUP</constant>,
 165     <constant>SD_BUS_CREDS_UNIT</constant>,
 166     <constant>SD_BUS_CREDS_SLICE</constant>,
 167     <constant>SD_BUS_CREDS_USER_UNIT</constant>,
 168     <constant>SD_BUS_CREDS_USER_SLICE</constant>,
 169     <constant>SD_BUS_CREDS_SESSION</constant>,
 170     <constant>SD_BUS_CREDS_OWNER_UID</constant>,
 171     <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
 172     <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
 173     <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
 174     <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
 175     <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
 176     <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
 177     <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
 178     <constant>SD_BUS_CREDS_TTY</constant>,
 179     <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
 180     <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
 181     <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
 182     value <constant>_SD_BUS_CREDS_ALL</constant> to request all
 183     supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
 184     constant may not be ORed into the mask for invocations of
 185     <function>sd_bus_creds_new_from_pid()</function>.</para>
 186
 187     <para>Fields can be retrieved from the credentials object using
 188     <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     and other functions which correspond directly to the constants
 190     listed above.</para>
 191
 192     <para>A mask of fields which were actually successfully retrieved
 193     can be retrieved with
 194     <function>sd_bus_creds_get_mask()</function>. If the credentials
 195     object was created with
 196     <function>sd_bus_creds_new_from_pid()</function>, this will be a
 197     subset of fields requested in <parameter>creds_mask</parameter>.
 198     </para>
 199
 200     <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
 201     function <function>sd_bus_creds_get_augmented_mask()</function>
 202     returns a bitmask of field constants. The mask indicates which
 203     credential fields have been retrieved in a non-atomic fashion. For
 204     credential objects created via
 205     <function>sd_bus_creds_new_from_pid()</function>, this mask will be
 206     identical to the mask returned by
 207     <function>sd_bus_creds_get_mask()</function>. However, for
 208     credential objects retrieved via
 209     <function>sd_bus_get_name_creds()</function>, this mask will be set
 210     for the credential fields that could not be determined atomically
 211     at peer connection time, and which were later added by reading
 212     augmenting credential data from
 213     <filename>/proc</filename>. Similarly, for credential objects
 214     retrieved via <function>sd_bus_get_owner_creds()</function>, the
 215     mask is set for the fields that could not be determined atomically
 216     at bus creation time, but have been augmented. Similarly, for
 217     credential objects retrieved via
 218     <function>sd_bus_message_get_creds()</function>, the mask is set
 219     for the fields that could not be determined atomically at message
 220     sending time, but have been augmented. The mask returned by
 221     <function>sd_bus_creds_get_augmented_mask()</function> is always a
 222     subset of (or identical to) the mask returned by
 223     <function>sd_bus_creds_get_mask()</function> for the same
 224     object. The latter call hence returns all credential fields
 225     available in the credential object, the former then marks the
 226     subset of those that have been augmented. Note that augmented
 227     fields are unsuitable for authorization decisions, as they may be
 228     retrieved at different times, thus being subject to races. Hence,
 229     augmented fields should be used exclusively for informational
 230     purposes.
 231     </para>
 232
 233     <para><function>sd_bus_creds_ref()</function> creates a new
 234     reference to the credentials object <parameter>c</parameter>. This
 235     object will not be destroyed until
 236     <function>sd_bus_creds_unref()</function> has been called as many
 237     times plus once more. Once the reference count has dropped to zero,
 238     <parameter>c</parameter> cannot be used anymore, so further
 239     calls to <function>sd_bus_creds_ref(c)</function> or
 240     <function>sd_bus_creds_unref(c)</function> are illegal.</para>
 241
 242     <para><function>sd_bus_creds_unref()</function> destroys a reference
 243     to <parameter>c</parameter>.</para>
 244
 245     <para><function>sd_bus_creds_unrefp()</function> is similar to
 246     <function>sd_bus_creds_unref()</function> but takes a pointer to a
 247     pointer to an <type>sd_bus_creds</type> object. This call is useful in
 248     conjunction with GCC's and LLVM's <ulink
 249     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
 250     Variable Attribute</ulink>. Note that this function is defined as
 251     inline function.</para>
 252
 253     <para><function>sd_bus_creds_ref()</function>,
 254     <function>sd_bus_creds_unref()</function> and
 255     <function>sd_bus_creds_unrefp()</function> execute no operation if
 256     the passed in bus credentials object is
 257     <constant>NULL</constant>.</para>
 258
 259   </refsect1>
 260
 261   <refsect1>
 262     <title>Return Value</title>
 263
 264     <para>On success, <function>sd_bus_creds_new_from_pid()</function>
 265     returns 0 or a positive integer. On failure, it returns a negative
 266     errno-style error code.</para>
 267
 268     <para><function>sd_bus_creds_get_mask()</function> returns the
 269     mask of successfully acquired fields.</para>
 270
 271     <para><function>sd_bus_creds_get_augmented_mask()</function>
 272     returns the mask of fields that have been augmented from data in
 273     <filename>/proc</filename>, and are thus not suitable for
 274     authorization decisions.</para>
 275
 276     <para><function>sd_bus_creds_ref()</function> always returns the
 277     argument.</para>
 278
 279     <para><function>sd_bus_creds_unref()</function> always returns
 280     <constant>NULL</constant>.</para>
 281   </refsect1>
 282
 283   <refsect1>
 284     <title>Reference ownership</title>
 285
 286     <para>Function <function>sd_bus_creds_new_from_pid()</function>
 287     creates a new object and the caller owns the sole reference. When
 288     not needed anymore, this reference should be destroyed with
 289     <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 290     </para>
 291   </refsect1>
 292
 293   <refsect1>
 294     <title>Errors</title>
 295
 296     <para>Returned errors may indicate the following problems:</para>
 297
 298     <variablelist>
 299
 300       <varlistentry>
 301         <term><constant>-ESRCH</constant></term>
 302
 303         <listitem><para>Specified <parameter>pid</parameter> could not
 304         be found.</para></listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term><constant>-EINVAL</constant></term>
 309
 310         <listitem><para>Specified parameter is invalid
 311         (<constant>NULL</constant> in case of output
 312         parameters).</para></listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term><constant>-ENOMEM</constant></term>
 317
 318         <listitem><para>Memory allocation failed.</para></listitem>
 319       </varlistentry>
 320
 321       <varlistentry>
 322         <term><constant>-EOPNOTSUPP</constant></term>
 323
 324         <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
 325       </varlistentry>
 326     </variablelist>
 327   </refsect1>
 328
 329   <refsect1>
 330     <title>Notes</title>
 331
 332     <para><function>sd_bus_creds_new_from_pid()</function> and the
 333     other calls described here are available as a shared library,
 334     which can be compiled and linked to with the
 335     <constant>libelogind</constant> <citerefentry
 336     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 337     file.</para>
 338   </refsect1>
 339
 340   <refsect1>
 341     <title>See Also</title>
 342
 343     <para>
 344       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 345       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 346       <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 347       <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 348       <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 349       <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 350     </para>
 351   </refsect1>
 352
 353 </refentry>