-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>int <parameter>b</parameter></paramdef>
+ <paramdef>uint64_t <parameter>flags</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<para><function>sd_bus_negotiate_fds()</function> controls whether
file descriptor passing shall be negotiated for the specified bus
- connection. Takes a bus object and a boolean, which when true
- enables file descriptor passing, and when false disables it. Note
+ connection. It takes a bus object and a boolean, which, when true,
+ enables file descriptor passing, and, when false, disables it. Note
that not all transports and servers support file descriptor
passing. To find out whether file descriptor passing is available
- after negotiation use
+ after negotiation, use
<citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
descriptor passing is always enabled for both sending and
receiving or for neither, but never only in one direction. By
- default file descriptor passing is negotiated for all
+ default, file descriptor passing is negotiated for all
connections.</para>
- <para>Note that when bus activation is used it is highly
+ <para>Note that when bus activation is used, it is highly
recommended to set the <option>AcceptFileDescriptors=</option>
setting in the <filename>.busname</filename> unit file to the same
setting as negotiated by the program ultimately activated. By
- default file descriptor passing is enabled for both.</para>
+ default, file descriptor passing is enabled for both.</para>
<para><function>sd_bus_negotiate_timestamps()</function> controls
whether implicit sender timestamps shall be attached automatically
- to all incoming messages. Takes a bus object and a boolean, which
- when true enables timestamping, and when false disables it. If
+ to all incoming messages. Takes a bus object and a boolean, which,
+ when true, enables timestamping, and, when false, disables it. If
this is disabled,
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_seqno</refentrytitle><manvolnum>3</manvolnum></citerefentry>
fail with <constant>-ENODATA</constant> on incoming messages. Note
that not all transports support timestamping of messages. On local
- transports the timestamping is applied by the kernel and cannot be
- manipulated by userspace.</para>
+ transports, the timestamping is applied by the kernel and cannot
+ be manipulated by userspace. By default, message timestamping is
+ not negotiated for all connections.</para>
<para><function>sd_bus_negotiate_creds()</function> controls
whether implicit sender credentials shall be attached
- automatically to all incoming messages. Takes a bus object and a
- bit mask value, which controls which credential parameters are
- attached. If this is not used,
- <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- fails with <constant>-ENODATA</constant> on incoming
- messages. Note that not all transports support attaching sender
- credentials to messages, or do not support all types of sender
- credential parameters. On local transports the sender credentials
- are attached by the kernel and cannot be manipulated by
- userspace. By default no sender credentials are attached.</para>
-
- <para>These functions may be called only before the connection has
- been started with
- <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+ automatically to all incoming messages. Takes a bus object, a
+ boolean indicating whether to enable or disable the credential
+ parts encoded in the bit mask value argument. Note that not all
+ transports support attaching sender credentials to messages, or do
+ not support all types of sender credential parameters, or might
+ suppress them under certain circumstances for individual
+ messages. On local transports, the sender credentials are attached
+ by the kernel and cannot be manipulated by userspace. By default,
+ no sender credentials are attached.</para>
+
+ <para>The <function>sd_bus_negotiate_fds()</function> function may
+ be called only before the connection has been started with
+ <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
+ <function>sd_bus_negotiate_timestamp()</function> and
+ <function>sd_bus_negotiate_creds()</function> also may be called
+ after a connection has been set up. Note that when operating on a
+ connection that is shared between multiple components of the same
+ program (for example via
+ <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
+ it is highly recommended to only enable additional per message
+ metadata fields, but never disable them again, in order not to
+ disable functionality needed by other components.</para>
</refsect1>
<refsect1>
<variablelist>
<varlistentry>
- <term><varname>-EPERM</varname></term>
+ <term><constant>-EPERM</constant></term>
<listitem><para>The bus connection has already been started.</para></listitem>
</varlistentry>
<para><function>sd_bus_negotiate_fs()</function> and the other
functions described here are available as a shared library, which
can be compiled and linked to with the
- <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
~ianmdlvl / elogind.git / blobdiff