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 systemd.
   7
   8   Copyright 2014 Lennart Poettering
   9
  10   systemd 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   systemd 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 systemd; 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>systemd</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;systemd/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_timestamp()</function> controls whether implicit sender
 103     timestamps shall be attached automatically to all incoming messages. Takes a bus object and a
 104     boolean, which, when true, enables timestamping, and, when false, disables it.  Use
 105     <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 106     <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 107     <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 108     to query the timestamps of incoming messages. If negotiation is disabled or not supported, these
 109     calls will fail with <constant>-ENODATA</constant>. Note that currently no transports support
 110     timestamping of messages. By default, message timestamping is not negotiated for
 111     connections.</para>
 112
 113     <para><function>sd_bus_negotiate_creds()</function> controls whether and which implicit sender
 114     credentials shall be attached automatically to all incoming messages. Takes a bus object and a
 115     boolean indicating whether to enable or disable the credential parts encoded in the bit mask
 116     value argument. Note that not all transports support attaching sender credentials to messages,
 117     or do not support all types of sender credential parameters, or might suppress them under
 118     certain circumstances for individual messages. Specifically, dbus1 only supports
 119     <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender credentials are suitable for
 120     authorization decisions. By default, only <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and
 121     <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In fact, these two credential fields
 122     are always sent along and cannot be turned off.</para>
 123
 124     <para>The <function>sd_bus_negotiate_fds()</function> function may
 125     be called only before the connection has been started with
 126     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
 127     <function>sd_bus_negotiate_timestamp()</function> and
 128     <function>sd_bus_negotiate_creds()</function> may also be called
 129     after a connection has been set up. Note that, when operating on a
 130     connection that is shared between multiple components of the same
 131     program (for example via
 132     <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>),
 133     it is highly recommended to only enable additional per message
 134     metadata fields, but never disable them again, in order not to
 135     disable functionality needed by other components.</para>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Return Value</title>
 140
 141     <para>On success, these functions return 0 or a
 142     positive integer. On failure, they return a negative errno-style
 143     error code.</para>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Errors</title>
 148
 149     <para>Returned errors may indicate the following problems:</para>
 150
 151     <variablelist>
 152       <varlistentry>
 153         <term><constant>-EPERM</constant></term>
 154
 155         <listitem><para>The bus connection has already been started.</para></listitem>
 156       </varlistentry>
 157     </variablelist>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Notes</title>
 162
 163     <para><function>sd_bus_negotiate_fds()</function> and the other
 164     functions described here are available as a shared library, which
 165     can be compiled and linked to with the
 166     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 167     file.</para>
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>See Also</title>
 172
 173     <para>
 174       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 175       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176       <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177       <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 178       <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 179       <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 180       <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 183     </para>
 184   </refsect1>
 185
 186 </refentry>