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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_bus_negotiate_fds" conditional="ENABLE_KDBUS">
  28
  29   <refentryinfo>
  30     <title>sd_bus_negotiate_fds</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_bus_negotiate_fds</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_bus_negotiate_fds</refname>
  50     <refname>sd_bus_negotiate_timestamps</refname>
  51     <refname>sd_bus_negotiate_creds</refname>
  52
  53     <refpurpose>Control feature negotiation on bus connections</refpurpose>
  54   </refnamediv>
  55
  56   <refsynopsisdiv>
  57     <funcsynopsis>
  58       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_bus_negotiate_fds</function></funcdef>
  62         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  63         <paramdef>int <parameter>b</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>int <function>sd_bus_negotiate_timestamp</function></funcdef>
  68         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  69         <paramdef>int <parameter>b</parameter></paramdef>
  70       </funcprototype>
  71
  72       <funcprototype>
  73         <funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
  74         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  75         <paramdef>int <parameter>b</parameter></paramdef>
  76         <paramdef>uint64_t <parameter>flags</parameter></paramdef>
  77       </funcprototype>
  78     </funcsynopsis>
  79   </refsynopsisdiv>
  80
  81   <refsect1>
  82     <title>Description</title>
  83
  84     <para><function>sd_bus_negotiate_fds()</function> controls whether
  85     file descriptor passing shall be negotiated for the specified bus
  86     connection. It takes a bus object and a boolean, which, when true,
  87     enables file descriptor passing, and, when false, disables it. Note
  88     that not all transports and servers support file descriptor
  89     passing. To find out whether file descriptor passing is available
  90     after negotiation, use
  91     <citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  92     and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
  93     descriptor passing is always enabled for both sending and
  94     receiving or for neither, but never only in one direction. By
  95     default, file descriptor passing is negotiated for all
  96     connections.</para>
  97
  98     <para>Note that when bus activation is used, it is highly
  99     recommended to set the <option>AcceptFileDescriptors=</option>
 100     setting in the <filename>.busname</filename> unit file to the same
 101     setting as negotiated by the program ultimately activated. By
 102     default, file descriptor passing is enabled for both.</para>
 103
 104     <para><function>sd_bus_negotiate_timestamps()</function> controls
 105     whether implicit sender timestamps shall be attached automatically
 106     to all incoming messages. Takes a bus object and a boolean, which,
 107     when true, enables timestamping, and, when false, disables it. If
 108     this is disabled,
 109     <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 110     <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 111     <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 112     fail with <constant>-ENODATA</constant> on incoming messages. Note
 113     that not all transports support timestamping of messages. On local
 114     transports, the timestamping is applied by the kernel and cannot
 115     be manipulated by userspace. By default, message timestamping is
 116     not negotiated for all connections.</para>
 117
 118     <para><function>sd_bus_negotiate_creds()</function> controls
 119     whether implicit sender credentials shall be attached
 120     automatically to all incoming messages. Takes a bus object, a
 121     boolean indicating whether to enable or disable the credential
 122     parts encoded in the bit mask value argument. Note that not all
 123     transports support attaching sender credentials to messages, or do
 124     not support all types of sender credential parameters, or might
 125     suppress them under certain circumstances for individual
 126     messages. On local transports, the sender credentials are attached
 127     by the kernel and cannot be manipulated by userspace. By default,
 128     no sender credentials are attached.</para>
 129
 130     <para>The <function>sd_bus_negotiate_fds()</function> function may
 131     be called only before the connection has been started with
 132     <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
 133     <function>sd_bus_negotiate_timestamp()</function> and
 134     <function>sd_bus_negotiate_creds()</function> also may be called
 135     after a connection has been set up. Note that when operating on a
 136     connection that is shared between multiple components of the same
 137     program (for example via
 138     <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
 139     it is highly recommended to only enable additional per message
 140     metadata fields, but never disable them again, in order not to
 141     disable functionality needed by other components.</para>
 142   </refsect1>
 143
 144   <refsect1>
 145     <title>Return Value</title>
 146
 147     <para>On success, these functions returns 0 or a
 148     positive integer. On failure, they return a negative errno-style
 149     error code.</para>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Errors</title>
 154
 155     <para>Returned errors may indicate the following problems:</para>
 156
 157     <variablelist>
 158       <varlistentry>
 159         <term><constant>-EPERM</constant></term>
 160
 161         <listitem><para>The bus connection has already been started.</para></listitem>
 162       </varlistentry>
 163     </variablelist>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>Notes</title>
 168
 169     <para><function>sd_bus_negotiate_fs()</function> and the other
 170     functions described here are available as a shared library, which
 171     can be compiled and linked to with the
 172     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 173     file.</para>
 174   </refsect1>
 175
 176   <refsect1>
 177     <title>See Also</title>
 178
 179     <para>
 180       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 181       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 182       <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 183       <citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 184       <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 185       <citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 186       <citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 187     </para>
 188   </refsect1>
 189
 190 </refentry>