sd_bus_creds_new_from_pid.xml revision f6f7a9848e27fbc1748aec9264e58a2aeaf736db
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Zbigniew Jędrzejewski-Szmek
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <title>sd_bus_creds_new_from_pid</title>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <contrib>A monkey with a typewriter</contrib>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <surname>Jędrzejewski-Szmek</surname>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <email>zbyszek@in.waw.pl</email>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refentrytitle>sd_bus_creds_new_from_pid</refentrytitle>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refname>sd_bus_creds_new_from_pid</refname>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refname>sd_bus_creds_get_mask</refname>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <refname>sd_bus_creds_get_augmented_mask</refname>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refname>sd_bus_creds_ref</refname>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refname>sd_bus_creds_unref</refname>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <funcdef>int <function>sd_bus_creds_new_from_pid</function></funcdef>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <paramdef>pid_t <parameter>pid</parameter></paramdef>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <paramdef>uint64_t <parameter>creds_mask</parameter></paramdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>sd_bus_creds **<parameter>ret</parameter></paramdef>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek </funcprototype>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <funcdef>uint64_t <function>sd_bus_creds_get_mask</function></funcdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek </funcprototype>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <funcprototype>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <funcdef>uint64_t <function>sd_bus_creds_get_augmented_mask</function></funcdef>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <paramdef>const sd_bus_creds *<parameter>c</parameter></paramdef>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering </funcprototype>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <funcdef>sd_bus_creds *<function>sd_bus_creds_ref</function></funcdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek </funcprototype>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
8dc385e7701726be69b681e2738a1d74a21b24f1Jan Engelhardt <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek </funcprototype>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_PID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_TID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_UID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_GID</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_COMM</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_TID_COMM</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_EXE</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_CMDLINE</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_CGROUP</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_UNIT</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_SLICE</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_USER_UNIT</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_USER_SLICE</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_SESSION</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_OWNER_UID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_DESCRIPTION</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_AUGMENT</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>_SD_BUS_CREDS_ALL</constant>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_new_from_pid()</function> creates a
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering new credentials object and fills it with information about the
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering process <parameter>pid</parameter>. The pointer to this object
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering will be stored in <parameter>ret</parameter> pointer. Note that
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering credential objects may also be created and retrieved via
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <para>The information that will be stored is determined by
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <parameter>creds_mask</parameter>. It may contain a subset of ORed
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek constants <constant>SD_BUS_CREDS_PID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_TID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_UID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_GID</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_SUPPLEMENTARY_GIDS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_COMM</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_TID_COMM</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_EXE</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_CMDLINE</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_CGROUP</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_UNIT</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_SLICE</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_USER_UNIT</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_USER_SLICE</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_SESSION</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_OWNER_UID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_EFFECTIVE_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_PERMITTED_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_INHERITABLE_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_BOUNDING_CAPS</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_SELINUX_CONTEXT</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_AUDIT_SESSION_ID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_AUDIT_LOGIN_UID</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>SD_BUS_CREDS_DESCRIPTION</constant>. Use the special
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering value <constant>_SD_BUS_CREDS_ALL</constant> to request all
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering supported fields. The <constant>SD_BUS_CREDS_AUGMENT</constant>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering may not be ORed into the mask for invocations of
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_new_from_pid()</function>.</para>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <para>Fields can be retrieved from the credentials object using
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek and other functions which correspond directly to the constants
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek listed above.</para>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para>A mask of fields which were actually successfully retrieved
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering can be retrieved with
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_get_mask()</function>. If the credentials
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering object was created with
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <function>sd_bus_creds_new_from_pid()</function>, this will be a
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek subset of fields requested in <parameter>creds_mask</parameter>.
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para>Similar to <function>sd_bus_creds_get_mask()</function> the
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering function <function>sd_bus_creds_get_augmented_mask()</function>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering returns a bitmask of field constants. The mask indicates which
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering credential fields have been retrieved in a non-atomic fashion. For
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering credential objects created via
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_new_from_pid()</function> this mask will be
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering identical to the mask returned by
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_get_mask()</function>. However, for
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering credential objects retrieved via
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_get_name_creds()</function> this mask will be set
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering for the credential fields that could not be determined atomically
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering at peer connection time, and which were later added by reading
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering augmenting credential data from
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <filename>/proc</filename>. Similar, for credential objects
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering retrieved via <function>sd_bus_get_owner_creds()</function> the
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering mask is set for the fields that could not be determined atomically
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering at bus creation time, but have been augmented. Similar, for
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering credential objects retrieved via
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_message_get_creds()</function> the mask is set
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering for the fields that could not be determined atomically at message
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering send time, but have been augmented. The mask returned by
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_get_augmented_mask()</function> is always a
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering subset of (or identical to) the mask returned by
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_get_mask()</function> for the same
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering object. The latter call hence returns all credential fields
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering available in the credential object, the former then marks the
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering subset of those that have been augmented. Note that augmented
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering fields are unsuitable for authorization decisions as they may be
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering retrieved at different times, thus being subject to races. Hence
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering augmented fields should be used exclusively for informational
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_ref()</function> creates a new
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek reference to the credentials object <parameter>c</parameter>. This
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek object will not be destroyed until
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <function>sd_bus_creds_unref()</function> has been called as many
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek times plus once more. Once the reference count has dropped to zero,
06b643e7f5a3b79005dd57497897ab7255fe3659Ruben Kerkhof <parameter>c</parameter> cannot be used anymore, so further
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek calls to <function>sd_bus_creds_ref(c)</function> or
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <function>sd_bus_creds_unref(c)</function> are illegal.</para>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_unref()</function> destroys a reference
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek to <parameter>c</parameter>.</para>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <para>On success, <function>sd_bus_creds_new_from_pid()</function>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek returns 0 or a positive integer. On failure, it returns a negative
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek errno-style error code.</para>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <para><function>sd_bus_creds_get_mask()</function> returns the
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek mask of successfully acquired fields.</para>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_get_augmented_mask()</function>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering returns the mask of fields that have been augmented from data in
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <filename>/proc</filename>, and are thus not suitable for
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering authorization decisions.</para>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_ref()</function> always returns the
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek argument.</para>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_unref()</function> always returns
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <constant>NULL</constant>.</para>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <title>Reference ownership</title>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <para>Function <function>sd_bus_creds_new_from_pid()</function>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek creates a new object and the caller owns the sole reference. When
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek not needed anymore, this reference should be destroyed with
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_creds_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <para>Returned errors may indicate the following problems:</para>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ESRCH</constant></term>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <listitem><para>Specified <parameter>pid</parameter> could not
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-EINVAL</constant></term>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <listitem><para>Specified parameter is invalid
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek (<constant>NULL</constant> in case of output
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ENOMEM</constant></term>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <listitem><para>Memory allocation failed.</para></listitem>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <varlistentry>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <term><constant>-EOPNOTSUPP</constant></term>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <listitem><para>One of the requested fields is unknown to the local system.</para></listitem>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering </varlistentry>
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <para><function>sd_bus_creds_new_from_pid()</function> and the
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering other calls described here are available as a shared library,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering which can be compiled and linked to with the
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <constant>libsystemd</constant> <citerefentry
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
4cf8496d0a5e85ec7610d166c5d35df3e6d02d1aZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>sd_bus_creds_get_pid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <citerefentry><refentrytitle>sd_bus_get_name_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <citerefentry><refentrytitle>sd_bus_get_owner_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f6f7a9848e27fbc1748aec9264e58a2aeaf736dbLennart Poettering <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>