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