man/sd_bus_negotiate_fds.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 elogind.
   7
   8   Copyright 2014 Lennart Poettering
   9
  10   elogind 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   elogind 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 elogind; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_bus_negotiate_fds">
  25
  26   <refentryinfo>
  27     <title>sd_bus_negotiate_fds</title>
  28     <productname>elogind</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_bus_negotiate_fds</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_bus_negotiate_fds</refname>
  47     <refname>sd_bus_negotiate_timestamp</refname>
  48     <refname>sd_bus_negotiate_creds</refname>
  49
  50     <refpurpose>Control feature negotiation on bus connections</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <funcsynopsis>
  55       <funcsynopsisinfo>#include &lt;elogind/sd-bus.h&gt;</funcsynopsisinfo>
  56
  57       <funcprototype>
  58         <funcdef>int <function>sd_bus_negotiate_fds</function></funcdef>
  59         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  60         <paramdef>int <parameter>b</parameter></paramdef>
  61       </funcprototype>
  62
  63       <funcprototype>
  64         <funcdef>int <function>sd_bus_negotiate_timestamp</function></funcdef>
  65         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  66         <paramdef>int <parameter>b</parameter></paramdef>
  67       </funcprototype>
  68
  69       <funcprototype>
  70         <funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
  71         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  72         <paramdef>int <parameter>b</parameter></paramdef>
  73         <paramdef>uint64_t <parameter>mask</parameter></paramdef>
  74       </funcprototype>
  75     </funcsynopsis>
  76   </refsynopsisdiv>
  77
  78   <refsect1>
  79     <title>Description</title>
  80
  81     <para><function>sd_bus_negotiate_fds()</function> controls whether
  82     file descriptor passing shall be negotiated for the specified bus
  83     connection. It takes a bus object and a boolean, which, when true,
  84     enables file descriptor passing, and, when false, disables
  85     it. Note that not all transports and servers support file
  86     descriptor passing. In particular, networked transports generally
  87     do not support file descriptor passing. To find out whether file
  88     descriptor passing is available after negotiation, use
  89     <citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  90     and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
  91     descriptor passing is always enabled for both sending and
  92     receiving or for neither, but never only in one direction. By
  93     default, file descriptor passing is negotiated for all
  94     connections.</para>
  95
  96     <para>Note that when bus activation is used, it is highly
  97     recommended to set the <option>AcceptFileDescriptors=</option>
  98     setting in the <filename>.busname</filename> unit file to the same
  99     setting as negotiated by the program ultimately activated. By
 100     default, file descriptor passing is enabled for both.</para>
 101
 102     <para><function>sd_bus_negotiate_timestamps()</function> controls
 103     whether implicit sender timestamps shall be attached automatically
 104     to all incoming messages. Takes a bus object and a boolean, which,
 105     when true, enables timestamping, and, when false, disables it.
 106     Use
 107     <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 108     <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 109     <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 110     to query the timestamps of incoming messages. If negotiation is
 111     disabled or not supported, these calls will fail with
 112     <constant>-ENODATA</constant>. Note that not all transports
 113     support timestamping of messages. Specifically, timestamping is
 114     only available on the kdbus transport, but not on dbus1. The
 115     timestamping is applied by the kernel and cannot be manipulated by
 116     userspace. By default, message timestamping is not negotiated for
 117     connections.</para>
 118
 119     <para><function>sd_bus_negotiate_creds()</function> controls
 120     whether and which implicit sender credentials shall be attached
 121     automatically to all incoming messages. Takes a bus object and a
 122     boolean indicating whether to enable or disable the credential
 123     parts encoded in the bit mask value argument. Note that not all
 124     transports support attaching sender credentials to messages, or do
 125     not support all types of sender credential parameters, or might
 126     suppress them under certain circumstances for individual
 127     messages. Specifically, implicit sender credentials on messages
 128     are only fully supported on kdbus transports, and dbus1 only
 129     supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender
 130     credentials are attached by the kernel and cannot be manipulated
 131     by userspace, and are thus suitable for authorization
 132     decisions. By default, only
 133     <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and
 134     <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In
 135     fact, these two credential fields are always sent along and cannot
 136     be turned off.</para>
 137
 138     <para>The <function>sd_bus_negotiate_fds()</function> function may
 139     be called only before the connection has been started with
 140     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
 141     <function>sd_bus_negotiate_timestamp()</function> and
 142     <function>sd_bus_negotiate_creds()</function> may also be called
 143     after a connection has been set up. Note that, when operating on a
 144     connection that is shared between multiple components of the same
 145     program (for example via
 146     <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>),
 147     it is highly recommended to only enable additional per message
 148     metadata fields, but never disable them again, in order not to
 149     disable functionality needed by other components.</para>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Return Value</title>
 154
 155     <para>On success, these functions return 0 or a
 156     positive integer. On failure, they return a negative errno-style
 157     error code.</para>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Errors</title>
 162
 163     <para>Returned errors may indicate the following problems:</para>
 164
 165     <variablelist>
 166       <varlistentry>
 167         <term><constant>-EPERM</constant></term>
 168
 169         <listitem><para>The bus connection has already been started.</para></listitem>
 170       </varlistentry>
 171     </variablelist>
 172   </refsect1>
 173
 174   <refsect1>
 175     <title>Notes</title>
 176
 177     <para><function>sd_bus_negotiate_fds()</function> and the other
 178     functions described here are available as a shared library, which
 179     can be compiled and linked to with the
 180     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 181     file.</para>
 182   </refsect1>
 183
 184   <refsect1>
 185     <title>See Also</title>
 186
 187     <para>
 188       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 189       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 190       <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 191       <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 192       <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 193       <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194       <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 195       <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 196       <citerefentry><refentrytitle>elogind.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 197     </para>
 198   </refsect1>
 199
 200 </refentry>