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