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