1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="sd_bus_negotiate_fds" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_bus_negotiate_fds</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_negotiate_fds</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_negotiate_fds</refname>
<refname>sd_bus_negotiate_timestamp</refname>
<refname>sd_bus_negotiate_creds</refname>
<refname>sd_bus_get_creds_mask</refname>
<refpurpose>Control feature negotiation on bus connections</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_negotiate_fds</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>int <parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_negotiate_timestamp</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>int <parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>int <parameter>b</parameter></paramdef>
<paramdef>uint64_t <parameter>mask</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_get_creds_mask</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>uint64_t *<parameter>mask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_negotiate_fds()</function> controls whether file descriptor passing shall be
negotiated for the specified bus connection. It takes a bus object and a boolean, which, when true,
enables file descriptor passing, and, when false, disables it. Note that not all transports and servers
support file descriptor passing. In particular, networked transports generally do not support file
descriptor passing. To find out whether file descriptor passing is available after negotiation, use
<citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file descriptor passing is always enabled
for both sending and receiving or for neither, but never only in one direction. By default, file
descriptor passing is negotiated for all connections.</para>
<para><function>sd_bus_negotiate_timestamp()</function> controls whether implicit sender timestamps shall
be attached automatically to all incoming messages. Takes a bus object and a boolean, which, when true,
enables timestamping, and, when false, disables it. Use
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to query the timestamps of incoming messages. If negotiation is disabled or not supported, these calls
will fail with <constant>-ENODATA</constant>. Note that currently no transports support timestamping of
messages. By default, message timestamping is not negotiated for connections.</para>
<para><function>sd_bus_negotiate_creds()</function> controls whether and which implicit sender
credentials shall be attached automatically to all incoming messages. Takes a bus object and a boolean
indicating whether to enable or disable the credential parts encoded in the bit mask value argument. Note
that not all transports support attaching sender credentials to messages, or do not support all types of
sender credential parameters, or might suppress them under certain circumstances for individual messages.
Specifically, dbus1 only supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender credentials
are suitable for authorization decisions. By default, only
<constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are
enabled. In fact, these two credential fields are always sent along and cannot be turned off.</para>
<para><function>sd_bus_get_creds_mask()</function> returns the set of sender credentials that was
negotiated to be attached to all incoming messages in <parameter>mask</parameter>. This value is an
upper boundary only. Hence, always make sure to explicitly check which credentials are attached to a
specific message before using it.</para>
<para>The <function>sd_bus_negotiate_fds()</function> function may be called only before the connection
has been started with
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
<function>sd_bus_negotiate_timestamp()</function> and <function>sd_bus_negotiate_creds()</function> may
also be called after a connection has been set up. Note that, when operating on a connection that is
shared between multiple components of the same program (for example via
<citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it
is highly recommended to only enable additional per message metadata fields, but never disable them
again, in order not to disable functionality needed by other components.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return a non-negative integer. On failure, they return a negative
errno-style error code.</para>
<refsect2>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EPERM</constant></term>
<listitem><para>The bus connection has already been started.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>An argument is invalid.</para>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOPKG</constant></term>
<listitem><para>The bus cannot be resolved.</para>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus was created in a different process, library or module instance.</para>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>History</title>
<para><function>sd_bus_negotiate_fds()</function>,
<function>sd_bus_negotiate_timestamp()</function>, and
<function>sd_bus_negotiate_creds()</function> were added in version 212.</para>
<para><function>sd_bus_get_creds_mask()</function> was added in version 246.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>
|
