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">
6 This file is part of systemd.
8 Copyright 2014 Lennart Poettering
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.
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.
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/>.
24 <refentry id=
"sd_bus_negotiate_fds">
27 <title>sd_bus_negotiate_fds
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>sd_bus_negotiate_fds
</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_bus_negotiate_fds
</refname>
47 <refname>sd_bus_negotiate_timestamp
</refname>
48 <refname>sd_bus_negotiate_creds
</refname>
50 <refpurpose>Control feature negotiation on bus connections
</refpurpose>
55 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
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>
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>
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>
79 <title>Description
</title>
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
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
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>
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>
133 <title>Return Value
</title>
135 <para>On success, these functions return
0 or a
136 positive integer. On failure, they return a negative errno-style
141 <title>Errors
</title>
143 <para>Returned errors may indicate the following problems:
</para>
147 <term><constant>-EPERM
</constant></term>
149 <listitem><para>The bus connection has already been started.
</para></listitem>
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>libsystemd
</constant> <citerefentry project='die-net'
><refentrytitle>pkg-config
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
165 <title>See Also
</title>
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>