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