[thirdparty/systemd.git] / man / sd_bus_creds_new_from_pid.xml

<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1+ -->

<refentry id="sd_bus_creds_new_from_pid" xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sd_bus_creds_new_from_pid</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sd_bus_creds_new_from_pid</refname>
    <refname>sd_bus_creds_get_mask</refname>
    <refname>sd_bus_creds_get_augmented_mask</refname>
    <refname>sd_bus_creds_ref</refname>
    <refname>sd_bus_creds_unref</refname>
    <refname>sd_bus_creds_unrefp</refname>

    <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>

      <funcprototype>
        <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
        <paramdef>pid_t <parameter>pid</parameter></paramdef>
        <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
        <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
        <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
        <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
        <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
        <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
      </funcprototype>

      <funcprototype>
        <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
        <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>

    <para>
      <constant>SD_BUS_CREDS_PID</constant>,
      <constant>SD_BUS_CREDS_PPID</constant>,
      <constant>SD_BUS_CREDS_TID</constant>,
      <constant>SD_BUS_CREDS_UID</constant>,
      <constant>SD_BUS_CREDS_EUID</constant>,
      <constant>SD_BUS_CREDS_SUID</constant>,
      <constant>SD_BUS_CREDS_FSUID</constant>,
      <constant>SD_BUS_CREDS_GID</constant>,
      <constant>SD_BUS_CREDS_EGID</constant>,
      <constant>SD_BUS_CREDS_SGID</constant>,
      <constant>SD_BUS_CREDS_FSGID</constant>,
      <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
      <constant>SD_BUS_CREDS_COMM</constant>,
      <constant>SD_BUS_CREDS_TID_COMM</constant>,
      <constant>SD_BUS_CREDS_EXE</constant>,
      <constant>SD_BUS_CREDS_CMDLINE</constant>,
      <constant>SD_BUS_CREDS_CGROUP</constant>,
      <constant>SD_BUS_CREDS_UNIT</constant>,
      <constant>SD_BUS_CREDS_SLICE</constant>,
      <constant>SD_BUS_CREDS_USER_UNIT</constant>,
      <constant>SD_BUS_CREDS_USER_SLICE</constant>,
      <constant>SD_BUS_CREDS_SESSION</constant>,
      <constant>SD_BUS_CREDS_OWNER_UID</constant>,
      <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
      <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
      <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
      <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
      <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
      <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
      <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
      <constant>SD_BUS_CREDS_TTY</constant>,
      <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
      <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
      <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
      <constant>SD_BUS_CREDS_AUGMENT</constant>,
      <constant>_SD_BUS_CREDS_ALL</constant>
    </para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><function>sd_bus_creds_new_from_pid()</function> creates a
    new credentials object and fills it with information about the
    process <parameter>pid</parameter>. The pointer to this object
    will be stored in the <parameter>ret</parameter> pointer. Note that
    credential objects may also be created and retrieved via
    <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
    <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

    <para>The information that will be stored is determined by
    <parameter>creds_mask</parameter>. It may contain a subset of ORed
    constants <constant>SD_BUS_CREDS_PID</constant>,
    <constant>SD_BUS_CREDS_PPID</constant>,
    <constant>SD_BUS_CREDS_TID</constant>,
    <constant>SD_BUS_CREDS_UID</constant>,
    <constant>SD_BUS_CREDS_EUID</constant>,
    <constant>SD_BUS_CREDS_SUID</constant>,
    <constant>SD_BUS_CREDS_FSUID</constant>,
    <constant>SD_BUS_CREDS_GID</constant>,
    <constant>SD_BUS_CREDS_EGID</constant>,
    <constant>SD_BUS_CREDS_SGID</constant>,
    <constant>SD_BUS_CREDS_FSGID</constant>,
    <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
    <constant>SD_BUS_CREDS_COMM</constant>,
    <constant>SD_BUS_CREDS_TID_COMM</constant>,
    <constant>SD_BUS_CREDS_EXE</constant>,
    <constant>SD_BUS_CREDS_CMDLINE</constant>,
    <constant>SD_BUS_CREDS_CGROUP</constant>,
    <constant>SD_BUS_CREDS_UNIT</constant>,
    <constant>SD_BUS_CREDS_SLICE</constant>,
    <constant>SD_BUS_CREDS_USER_UNIT</constant>,
    <constant>SD_BUS_CREDS_USER_SLICE</constant>,
    <constant>SD_BUS_CREDS_SESSION</constant>,
    <constant>SD_BUS_CREDS_OWNER_UID</constant>,
    <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
    <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
    <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
    <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
    <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
    <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
    <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
    <constant>SD_BUS_CREDS_TTY</constant>,
    <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
    <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>, and
    <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
    value <constant>_SD_BUS_CREDS_ALL</constant> to request all
    supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
    constant may not be ORed into the mask for invocations of
    <function>sd_bus_creds_new_from_pid()</function>.</para>

    <para>Fields can be retrieved from the credentials object using
    <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    and other functions which correspond directly to the constants
    listed above.</para>

    <para>A mask of fields which were actually successfully retrieved
    can be retrieved with
    <function>sd_bus_creds_get_mask()</function>. If the credentials
    object was created with
    <function>sd_bus_creds_new_from_pid()</function>, this will be a
    subset of fields requested in <parameter>creds_mask</parameter>.
    </para>

    <para>Similar to <function>sd_bus_creds_get_mask()</function>, the
    function <function>sd_bus_creds_get_augmented_mask()</function>
    returns a bitmask of field constants. The mask indicates which
    credential fields have been retrieved in a non-atomic fashion. For
    credential objects created via
    <function>sd_bus_creds_new_from_pid()</function>, this mask will be
    identical to the mask returned by
    <function>sd_bus_creds_get_mask()</function>. However, for
    credential objects retrieved via
    <function>sd_bus_get_name_creds()</function>, this mask will be set
    for the credential fields that could not be determined atomically
    at peer connection time, and which were later added by reading
    augmenting credential data from
    <filename>/proc</filename>. Similarly, for credential objects
    retrieved via <function>sd_bus_get_owner_creds()</function>, the
    mask is set for the fields that could not be determined atomically
    at bus creation time, but have been augmented. Similarly, for
    credential objects retrieved via
    <function>sd_bus_message_get_creds()</function>, the mask is set
    for the fields that could not be determined atomically at message
    sending time, but have been augmented. The mask returned by
    <function>sd_bus_creds_get_augmented_mask()</function> is always a
    subset of (or identical to) the mask returned by
    <function>sd_bus_creds_get_mask()</function> for the same
    object. The latter call hence returns all credential fields
    available in the credential object, the former then marks the
    subset of those that have been augmented. Note that augmented
    fields are unsuitable for authorization decisions, as they may be
    retrieved at different times, thus being subject to races. Hence,
    augmented fields should be used exclusively for informational
    purposes.
    </para>

    <para><function>sd_bus_creds_ref()</function> creates a new
    reference to the credentials object <parameter>c</parameter>. This
    object will not be destroyed until
    <function>sd_bus_creds_unref()</function> has been called as many
    times plus once more. Once the reference count has dropped to zero,
    <parameter>c</parameter> cannot be used anymore, so further
    calls to <function>sd_bus_creds_ref(c)</function> or
    <function>sd_bus_creds_unref(c)</function> are illegal.</para>

    <para><function>sd_bus_creds_unref()</function> destroys a reference
    to <parameter>c</parameter>.</para>

    <para><function>sd_bus_creds_unrefp()</function> is similar to
    <function>sd_bus_creds_unref()</function> but takes a pointer to a
    pointer to an <type>sd_bus_creds</type> object. This call is useful in
    conjunction with GCC's and LLVM's <ulink
    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
    Variable Attribute</ulink>. Note that this function is defined as
    inline function.</para>

    <para><function>sd_bus_creds_ref()</function>,
    <function>sd_bus_creds_unref()</function> and
    <function>sd_bus_creds_unrefp()</function> execute no operation if
    the passed in bus credentials object is
    <constant>NULL</constant>.</para>

  </refsect1>

  <refsect1>
    <title>Return Value</title>

    <para>On success, <function>sd_bus_creds_new_from_pid()</function>
    returns 0 or a positive integer. On failure, it returns a negative
    errno-style error code.</para>

    <para><function>sd_bus_creds_get_mask()</function> returns the
    mask of successfully acquired fields.</para>

    <para><function>sd_bus_creds_get_augmented_mask()</function>
    returns the mask of fields that have been augmented from data in
    <filename>/proc</filename>, and are thus not suitable for
    authorization decisions.</para>

    <para><function>sd_bus_creds_ref()</function> always returns the
    argument.</para>

    <para><function>sd_bus_creds_unref()</function> always returns
    <constant>NULL</constant>.</para>
  </refsect1>

  <refsect1>
    <title>Reference ownership</title>

    <para>Function <function>sd_bus_creds_new_from_pid()</function>
    creates a new object and the caller owns the sole reference. When
    not needed anymore, this reference should be destroyed with
    <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
    </para>

    <refsect2>
      <title>Errors</title>

      <para>Returned errors may indicate the following problems:</para>

      <variablelist>

        <varlistentry>
          <term><constant>-ESRCH</constant></term>

          <listitem><para>Specified <parameter>pid</parameter> could not be found.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-EINVAL</constant></term>

          <listitem><para>Specified parameter is invalid (<constant>NULL</constant> in case of output
          parameters).</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-ENOMEM</constant></term>

          <listitem><para>Memory allocation failed.</para></listitem>
        </varlistentry>

        <varlistentry>
          <term><constant>-EOPNOTSUPP</constant></term>

          <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <xi:include href="libsystemd-pkgconfig.xml" />

  <refsect1>
    <title>See Also</title>

    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
    </para>
  </refsect1>

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