dasharo/systemd
0
0
Fork 0
mirror of https://github.com/Dasharo/systemd.git synced 2026-03-06 15:02:31 -08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7714 from poettering/sd-bus-watch-connect

Browse Source 
many sd-bus improvements
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
2018-01-05 19:46:38 +01:00
committed by GitHub
parent 65d36b4950 f3c33b234d
commit 2df4611205
70 changed files with 3128 additions and 1066 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
TODO
View File

@@ -35,6 +35,9 @@ Features:
* add bpf-based implementation of devices cgroup controller logic for compat with cgroupsv2 as supported by newest kernel
* sd-bus: add vtable flag, that may be used to request client creds implicitly
and asynchronously before dispatching the operation
* implement transient socket unit.
* make systemd-run create transient path and socket unit.
@@ -56,8 +59,6 @@ Features:
the runtime dir as we maintain for the fdstore: i.e. keep it around as long
as the unit is running or has a job queued.
* add async version of sd_bus_add_match and make use of that
* support projid-based quota in machinectl for containers, and then drop
implicit btrfs loopback magic in machined
@@ -495,14 +496,12 @@ Features:
- see if we can introduce a new sd_bus_get_owner_machine_id() call to retrieve the machine ID of the machine of the bus itself
- see if we can drop more message validation on the sending side
- add API to clone sd_bus_message objects
- make AddMatch calls on dbus1 transports async?
- longer term: priority inheritance
- dbus spec updates:
- NameLost/NameAcquired obsolete
- GVariant
- path escaping
- update systemd.special(7) to mention that dbus.socket is only about the compatibility socket now
- test bloom filter generation indexes
* sd-event
- allow multiple signal handlers per signal?

10
man/busctl.xml
View File

@@ -241,6 +241,16 @@
</listitem>
</varlistentry>
<varlistentry>
<term><option>--watch-bind=</option><replaceable>BOOL</replaceable></term>
<listitem>
<para>Controls whether to wait for the specified <constant>AF_UNIX</constant> bus socket to appear in the
file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
the socket is created and then connect to it.</para>
</listitem>
</varlistentry>
<xi:include href="user-system-options.xml" xpointer="user" />
<xi:include href="user-system-options.xml" xpointer="system" />
<xi:include href="user-system-options.xml" xpointer="host" />

21
man/rules/meson.build
View File

@@ -105,7 +105,12 @@ manpages = [
['sd-journal', '3', [], ''],
['sd-login', '3', [], 'HAVE_PAM'],
['sd_booted', '3', [], ''],
['sd_bus_add_match', '3', [], ''],
['sd_bus_add_match',
'3',
['sd_bus_add_match_async',
'sd_bus_match_signal',
'sd_bus_match_signal_async'],
''],
['sd_bus_creds_get_pid',
'3',
['sd_bus_creds_get_audit_login_uid',
@@ -181,6 +186,7 @@ manpages = [
['SD_BUS_ERROR_END', 'SD_BUS_ERROR_MAP', 'sd_bus_error_map'],
''],
['sd_bus_get_fd', '3', [], ''],
['sd_bus_is_open', '3', ['sd_bus_is_ready'], ''],
['sd_bus_message_append', '3', ['sd_bus_message_appendv'], ''],
['sd_bus_message_append_array',
'3',
@@ -200,6 +206,7 @@ manpages = [
['sd_bus_message_get_realtime_usec', 'sd_bus_message_get_seqnum'],
''],
['sd_bus_message_read_basic', '3', [], ''],
['sd_bus_message_set_destination', '3', ['sd_bus_message_set_sender'], ''],
['sd_bus_negotiate_fds',
'3',
['sd_bus_negotiate_creds', 'sd_bus_negotiate_timestamp'],
@@ -210,7 +217,15 @@ manpages = [
['sd_bus_path_decode', 'sd_bus_path_decode_many', 'sd_bus_path_encode_many'],
''],
['sd_bus_process', '3', [], ''],
['sd_bus_request_name', '3', ['sd_bus_release_name'], ''],
['sd_bus_request_name',
'3',
['sd_bus_release_name',
'sd_bus_release_name_async',
'sd_bus_request_name_async'],
''],
['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''],
['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''],
['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
['sd_bus_track_add_name',
'3',
['sd_bus_track_add_sender',
@@ -655,6 +670,7 @@ manpages = [
['systemd', '1', ['init'], ''],
['systemd.automount', '5', [], ''],
['systemd.device', '5', [], ''],
['systemd.dnssd', '5', [], 'ENABLE_RESOLVE'],
['systemd.environment-generator', '7', [], 'ENABLE_ENVIRONMENT_D'],
['systemd.exec', '5', [], ''],
['systemd.generator', '7', [], ''],
@@ -663,7 +679,6 @@ manpages = [
['systemd.link', '5', [], ''],
['systemd.mount', '5', [], ''],
['systemd.netdev', '5', [], 'ENABLE_NETWORKD'],
['systemd.dnssd', '5', [], 'ENABLE_RESOLVE'],
['systemd.network', '5', [], 'ENABLE_NETWORKD'],
['systemd.nspawn', '5', [], ''],
['systemd.offline-updates', '7', [], ''],

5
man/runlevel.xml
View File

@@ -173,10 +173,9 @@
<variablelist>
<varlistentry>
<term><filename>/var/run/utmp</filename></term>
<term><filename>/run/utmp</filename></term>
<listitem><para>The utmp database <command>runlevel</command>
reads the previous and current runlevel
<listitem><para>The utmp database <command>runlevel</command> reads the previous and current runlevel
from.</para></listitem>
</varlistentry>
</variablelist>

139
man/sd_bus_add_match.xml
View File

@@ -45,14 +45,24 @@
<refnamediv>
<refname>sd_bus_add_match</refname>
<refname>sd_bus_add_match_async</refname>
<refname>sd_bus_match_signal</refname>
<refname>sd_bus_match_signal_async</refname>
<refpurpose>Add a match rule for message dispatching</refpurpose>
<refpurpose>Add a match rule for incoming message dispatching</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
<paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_add_match</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
@@ -63,65 +73,122 @@
</funcprototype>
<funcprototype>
<funcdef>typedef int (*<function>sd_bus_message_handler_t</function>)</funcdef>
<paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
<funcdef>int <function>sd_bus_add_match_async</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
<paramdef>const char *<parameter>match</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>install_callback</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
<paramdef>sd_bus_error *<parameter>ret_error</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_match_signal</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
<paramdef>const char *<parameter>sender</parameter></paramdef>
<paramdef>const char *<parameter>path</parameter></paramdef>
<paramdef>const char *<parameter>interface</parameter></paramdef>
<paramdef>const char *<parameter>member</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_match_signal_async</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
<paramdef>const char *<parameter>sender</parameter></paramdef>
<paramdef>const char *<parameter>path</parameter></paramdef>
<paramdef>const char *<parameter>interface</parameter></paramdef>
<paramdef>const char *<parameter>member</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>install_callback</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<function>sd_bus_add_match()</function> installs a match rule for incoming messages received on the specified bus
connection object <parameter>bus</parameter>. The syntax of the match rule expression passed in
<parameter>match</parameter> is described in the <ulink
url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. The specified handler
function <parameter>callback</parameter> is called for eaching incoming message matching the specified
expression, the <parameter>userdata</parameter> parameter is passed as-is to the callback function.
<para><function>sd_bus_add_match()</function> installs a match rule for messages received on the specified bus
connection object <parameter>bus</parameter>. The syntax of the match rule expression passed in
<parameter>match</parameter> is described in the <ulink
url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus Specification</ulink>. The specified handler
function <parameter>callback</parameter> is called for eaching incoming message matching the specified expression,
the <parameter>userdata</parameter> parameter is passed as-is to the callback function. The match is installed
synchronously when connected to a bus broker, i.e. the call sends a control message requested the match to be added
to the broker and waits until the broker confirms the match has been installed successfully.</para>
<para><function>sd_bus_add_match_async()</function> operates very similar to
<function>sd_bus_match_signal()</function>, however it installs the match asynchronously, in a non-blocking
fashion: a request is sent to the broker, but the call does not wait for a response. The
<parameter>install_callback</parameter> function is called when the response is later received, with the response
message from the broker as parameter. If this function is specified as <constant>NULL</constant> a default
implementation is used that terminates the bus connection should installing the match fail.</para>
<para><function>sd_bus_match_signal()</function> is very similar to <function>sd_bus_add_match()</function>, but
only matches signals, and instead of a match expression accepts four parameters: <parameter>sender</parameter> (the
service name of the sender), <parameter>path</parameter> (the object path of the emitting object),
<parameter>interface</parameter> (the interface the signal belongs to), <parameter>member</parameter> (the signal
name), from which the match string is internally generated. Optionally, these parameters may be specified as
<constant>NULL</constant> in which case the relevant field of incoming signals is not tested.</para>
<para><function>sd_bus_match_signal_async()</function> is combines the signal matching logic of
<function>sd_bus_match_signal()</function> with the asynchronous behaviour of
<function>sd_bus_add_match_async()</function>.</para>
<para>On success, and if non-<constant>NULL</constant>, the <parameter>slot</parameter> return parameter will be
set to a slot object that may be used as a reference to the installed match, and may be utilized to remove it again
at a later time with
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If specified
as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the
match cannot be removed independently.</para>
<para>The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should
not call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
on it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
<citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create a
new reference.</para>
<para>If an error occurs during the callback invocation, the callback should return a negative error number
(optionally, a more precise error may be returned in <parameter>ret_error</parameter>, as well). If it wants other
callbacks that match the same rule to be called, it should return 0. Otherwise it should return a positive integer.
</para>
<para>
On success, and if non-<constant>NULL</constant>, the <parameter>slot</parameter> return parameter will be set to
a slot object that may be used as a reference to the installed match, and may be utilized to remove it again at a
later time with
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
specified as <constant>NULL</constant> the lifetime of the match is bound to the lifetime of the bus object itself, and the match
cannot be removed independently.
</para>
<para>
The message <parameter>m</parameter> passed to the callback is only borrowed, that is, the callback should not
call <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> on
it. If the callback wants to hold on to the message beyond the lifetime of the callback, it needs to call
<citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to create
a new reference.
</para>
<para>
If an error occurs during the callback invocation, the callback should return a negative error number. If it
wants other callbacks that match the same rule to be called, it should return 0. Otherwise it should return a
positive integer.
</para>
<para>If the <parameter>bus</parameter> refers to a direct connection (i.e. not a bus connection, as set with
<citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>) the
match is only installed on the client side, and the synchronous and asynchronous functions operate the same.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>
On success, <function>sd_bus_add_match()</function> returns 0 or a positive integer. On failure, it returns a
negative errno-style error code.
On success, <function>sd_bus_add_match()</function> and the other calls return 0 or a positive integer. On
failure, they return a negative errno-style error code.
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_bus_add_match()</function> and the other functions described here are available as a shared
library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_bus_client</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

137
man/sd_bus_is_open.xml Normal file
View File

@@ -0,0 +1,137 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
This file is part of systemd.
Copyright 2017 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_bus_is_open">
<refentryinfo>
<title>sd_bus_is_open</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_is_open</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_is_open</refname>
<refname>sd_bus_is_ready</refname>
<refpurpose>Check whether the a bus connection is open or ready.</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_is_open</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_is_ready</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_is_open()</function> checks whether the specified bus connection is open, i.e. in the
process of being established, already established or in the process of being torn down. It returns zero when the
connection has not been started yet
(i.e. <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry> or some
equivalent call has not been invoked yet), or is fully terminated again (for example after
<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>), it returns
positive otherwise.</para>
<para><function>sd_bus_is_ready()</function> checks whether the specified connection is fully established,
i.e. completed the connection and authentication phases of the protocol and received the
<function>Hello()</function> method call response, and is not in the process of being torn down again. It returns
zero outside of this state, and positive otherwise. Effectively, this function returns positive while regular
messages can be sent or received on the connection.</para>
<para>To be notified when the connection is fully established, use
<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
install a match for the <function>Connected()</function> signal on the
<literal>org.freedesktop.DBus.Local</literal> interface. To be notified when the connection is torn down again,
install a match for the <function>Disconnected()</function> signal on the
<literal>org.freedesktop.DBus.Local</literal> interface.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_bus_is_open()</function> and <function>sd_bus_is_ready()</function> are available as
a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

137
man/sd_bus_message_set_destination.xml Normal file
View File

@@ -0,0 +1,137 @@
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
This file is part of systemd.
Copyright 2017 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_bus_message_set_destination">
<refentryinfo>
<title>sd_bus_message_set_destination</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_message_set_destination</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_message_set_destination</refname>
<refname>sd_bus_message_set_sender</refname>
<refpurpose>Set the destination or sender service name of a bus message</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_message_set_destination</function></funcdef>
<paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
<paramdef>const char *<parameter>destination</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_message_set_sender</function></funcdef>
<paramdef>sd_bus_message *<parameter>message</parameter></paramdef>
<paramdef>const char *<parameter>sender</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_message_set_destination()</function> sets the destination service name for the specified bus
message object. The specified name must be a valid unique or well-known service name.</para>
<para><function>sd_bus_message_set_sender()</function> sets the sender service name for the specified bus message
object. The specified name must be a valid unique or well-known service name. This function is useful only for
messages to send on direct connections as for connections to bus brokers the broker will fill in the destination
field anyway, and the sender field set by original sender is ignored.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style
error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>A specified parameter is invalid.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EPERM</constant></term>
<listitem><para>The message is already sealed.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EEXIST</constant></term>
<listitem><para>The message already has a destination or sender field set.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The <function>sd_bus_message_set_destination()</function> and
<function>sd_bus_message_set_sender()</function> interfaces
are available as a shared library, which can be compiled and
linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

138
man/sd_bus_request_name.xml
View File

@@ -46,7 +46,9 @@
<refnamediv>
<refname>sd_bus_request_name</refname>
<refname>sd_bus_request_name_async</refname>
<refname>sd_bus_release_name</refname>
<refname>sd_bus_release_name_async</refname>
<refpurpose>Request or release a well-known service name on a bus</refpurpose>
</refnamediv>
@@ -61,71 +63,103 @@
<paramdef>uint64_t <parameter>flags</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_request_name_async</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>uint64_t <parameter>flags</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_release_name</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_release_name_async</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>sd_bus_slot **<parameter>slot</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
<paramdef>sd_bus_message_handler_t <parameter>callback</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_request_name()</function> requests a
well-known service name on a bus. It takes a bus connection, a
valid bus name and a flags parameter. The flags parameter is a
combination of the following flags:</para>
<para><function>sd_bus_request_name()</function> requests a well-known service name on a bus. It takes a bus
connection, a valid bus name and a flags parameter. The flags parameter is a combination of the following
flags:</para>
<variablelist>
<varlistentry>
<term><varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname></term>
<listitem><para>After acquiring the name successfully, permit
other peers to take over the name when they try to acquire it
with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag
set. If <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is
not set on the original request, such a request by other peers
will be denied.</para></listitem>
<listitem><para>After acquiring the name successfully, permit other peers to take over the name when they try
to acquire it with the <varname>SD_BUS_NAME_REPLACE_EXISTING</varname> flag set. If
<varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> is not set on the original request, such a request by other
peers will be denied.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SD_BUS_NAME_REPLACE_EXISTING</varname></term>
<listitem><para>Take over the name if it is already acquired
by another peer, and that other peer has permitted takeover by
setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while
acquiring it.</para></listitem>
<listitem><para>Take over the name if it is already acquired by another peer, and that other peer has permitted
takeover by setting <varname>SD_BUS_NAME_ALLOW_REPLACEMENT</varname> while acquiring it.</para></listitem>
</varlistentry>
<varlistentry>
<term><varname>SD_BUS_NAME_QUEUE</varname></term>
<listitem><para>Queue the acquisition of the name when the
name is already taken.</para></listitem>
<listitem><para>Queue the acquisition of the name when the name is already taken.</para></listitem>
</varlistentry>
</variablelist>
<para><function>sd_bus_release_name()</function> releases an
acquired well-known name. It takes a bus connection and a valid
bus name as parameters.</para>
<para><function>sd_bus_request_name()</function> operates in a synchronous fashion: a message requesting the name
is sent to the bus broker, and the call waits until the broker responds.</para>
<para><function>sd_bus_request_name_async()</function> is an asynchronous version of of
<function>sd_bus_release_name()</function>. Instead of waiting for the request to complete, the request message is
enqueued. The specified <parameter>callback</parameter> will be called when the broker's response is received. If
the parameter is specified as <constant>NULL</constant> a default implementation is used instead which will
terminate the connection when the name cannot be acquired. The function returns a slot object in its
<parameter>slot</parameter> parameter — if it is passed as non-<constant>NULL</constant> — which may be used as a
reference to the name request operation. Use
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry> to destroy
this reference. Note that destroying the reference will not unregister the name, but simply ensure the specified
callback is no longer called.</para>
<para><function>sd_bus_release_name()</function> releases an acquired well-known name. It takes a bus connection
and a valid bus name as parameters. This function operates synchronously, sending a release request message to the
bus broker and waiting for it to reply.</para>
<para><function>sd_bus_release_name_async()</function> is an asynchronous version of
<function>sd_bus_release_name()</function>. The specified <parameter>callback</parameter> function is called when
the name has been released successfully. If specified as <constant>NULL</constant> a generic implementation is used
that ignores the result of the operation. As above, the <parameter>slot</parameter> (if
non-<constant>NULL</constant>) is set to an object that may be used to reference the operation.</para>
<para>These functions are supported only on bus connections, i.e. connections to a bus broker and not on direct
connections.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these calls return 0 or a positive integer. On
failure, these calls return a negative errno-style error
code.</para>
<para>On success, these calls return 0 or a positive integer. On failure, these calls return a negative errno-style
error code.</para>
<para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified,
<function>sd_bus_request_name()</function> will return 0 when the
name is already taken by another peer and the client has been
added to the queue for the name. In that case, the caller can
subscribe to <literal>NameOwnerChanged</literal> signals to be
notified when the name is successfully acquired.
<function>sd_bus_request_name()</function> returns &gt; 0 when the
name has immediately been acquired successfully.</para>
<para>If <varname>SD_BUS_NAME_QUEUE</varname> is specified, <function>sd_bus_request_name()</function> will return
0 when the name is already taken by another peer and the client has been added to the queue for the name. In that
case, the caller can subscribe to <literal>NameOwnerChanged</literal> signals to be notified when the name is
successfully acquired. <function>sd_bus_request_name()</function> returns &gt; 0 when the name has immediately
been acquired successfully.</para>
</refsect1>
<refsect1>
@@ -137,56 +171,50 @@
<varlistentry>
<term><constant>-EALREADY</constant></term>
<listitem><para>The caller already is the owner of the
specified name.</para></listitem>
<listitem><para>The caller already is the owner of the specified name.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EEXIST</constant></term>
<listitem><para>The name has already been acquired by a
different peer, and SD_BUS_NAME_REPLACE_EXISTING was not
specified or the other peer did not specify
SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the
<listitem><para>The name has already been acquired by a different peer, and SD_BUS_NAME_REPLACE_EXISTING was
not specified or the other peer did not specify SD_BUS_NAME_ALLOW_REPLACEMENT while acquiring the
name.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESRCH</constant></term>
<listitem><para>It was attempted to release a name that is
currently not registered on the bus.</para></listitem>
<listitem><para>It was attempted to release a name that is currently not registered on the
bus.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EADDRINUSE</constant></term>
<listitem><para>It was attempted to release a name that is
owned by a different peer on the bus.</para></listitem>
<listitem><para>It was attempted to release a name that is owned by a different peer on the
bus.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>A specified parameter is invalid. This is also
generated when the requested name is a special service name
reserved by the D-Bus specification, or when the operation is
requested on a connection that does not refer to a
bus.</para></listitem>
<listitem><para>A specified parameter is invalid. This is also generated when the requested name is a special
service name reserved by the D-Bus specification, or when the operation is requested on a connection that does
not refer to a bus.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOTCONN</constant></term>
<listitem><para>The bus connection has been
disconnected.</para></listitem>
<listitem><para>The bus connection has been disconnected.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a
different process than the current one.</para></listitem>
<listitem><para>The bus connection has been created in a different process than the current
one.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
@@ -194,12 +222,9 @@
<refsect1>
<title>Notes</title>
<para>The <function>sd_bus_acquire_name()</function> and
<function>sd_bus_release_name()</function> interfaces are
available as a shared library, which can be compiled and linked to
with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
<para>The <function>sd_bus_acquire_name()</function> and the other interfaces described here are available as a
shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
</refsect1>
<refsect1>
@@ -208,7 +233,8 @@
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_slot_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

143
man/sd_bus_set_connected_signal.xml Normal file
View File

@@ -0,0 +1,143 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
This file is part of systemd.
Copyright 2017 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_bus_set_connected_signal">
<refentryinfo>
<title>sd_bus_set_connected_signal</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_set_connected_signal</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_set_connected_signal</refname>
<refname>sd_bus_get_connected_signal</refname>
<refpurpose>Control emmission of local connection establishment signal on bus connections</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_set_connected_signal</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>int <parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_get_connected_signal</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_set_connected_signal()</function> may be used to control whether a local, synthetic
<function>Connected()</function> signal message shall be generated and enqueued for dispatching when the connection
is fully established. If the <parameter>b</parameter> parameter is zero the message is not generated (the default),
otherwise it is generated.</para>
<para><function>sd_bus_get_connected_signal()</function> may be used to query whether this feature is enabled. It
returns zero if not, positive otherwise.</para>
<para>The <function>Connected()</function> signal message is generated from the
<literal>org.freedesktop.DBus.Local</literal> service and interface, and
<literal>/org/freedesktop/DBus/Local</literal> object path. Use
<citerefentry><refentrytitle>sd_bus_match_signal_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
match on this signal.</para>
<para>This message is particularly useful on slow transports where connections take a long time to be
established. This is especially the case when
<citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry> is
used. The signal is generated when the
<citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> returns
positive for the first time.</para>
<para>The <function>Connected()</function> signal corresponds with the <function>Disconnected()</function> signal
that is synthesized locally when the connection is terminated. The latter is generated unconditionally however,
unlike the former which needs to be enabled explicitly before it is generated, with
<function>sd_bus_set_connected_signal()</function>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_bus_set_connected_signal()</function> and <function>sd_bus_get_connected_signal()</function> are available as
a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_match_signal_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

136
man/sd_bus_set_sender.xml Normal file
View File

@@ -0,0 +1,136 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
This file is part of systemd.
Copyright 2017 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_bus_set_sender">
<refentryinfo>
<title>sd_bus_set_sender</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_set_sender</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_set_sender</refname>
<refname>sd_bus_get_sender</refname>
<refpurpose>Configure default sender for outgoing messages</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_set_sender</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>const char* <parameter>name</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_get_sender</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>const char** <parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_set_sender()</function> configures the default sender service name to use for outgoing
messages. The service name specified in the <parameter>name</parameter> parameter is set on all outgoing messages
that are sent on the connection and have no sender set yet, for example through
<citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note
that this function is only supported on direct connections, i.e. not on connections to a bus broker as the broker
will fill in the sender service name automatically anyway. By default no sender name is configured, and hence
messages are sent without sender field set. If the <parameter>name</parameter> parameter is specified as
<constant>NULL</constant> the default sender service name is cleared, returning to the default state if a default
sender service name was set before. If passed as non-<constant>NULL</constant> the specified name must be a valid
unique or well-known service name.</para>
<para><function>sd_bus_get_sender()</function> may be used to query the current default service name for outgoing
messages.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a different process.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EPERM</constant></term>
<listitem><para>The specified bus connection object is a not a direct but a brokered connection.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_bus_set_sender()</function> and <function>sd_bus_get_sender()</function> are available as
a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

152
man/sd_bus_set_watch_bind.xml Normal file
View File

@@ -0,0 +1,152 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
SPDX-License-Identifier: LGPL-2.1+
This file is part of systemd.
Copyright 2017 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_bus_set_watch_bind">
<refentryinfo>
<title>sd_bus_set_watch_bind</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_bus_set_watch_bind</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_bus_set_watch_bind</refname>
<refname>sd_bus_get_watch_bind</refname>
<refpurpose>Control socket binding watching on bus connections</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_bus_set_watch_bind</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
<paramdef>int <parameter>b</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_bus_get_watch_bind</function></funcdef>
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_bus_set_watch_bind()</function> may be used to enable or disable client-side watching of server
socket binding for a bus connection object. If the <parameter>b</parameter> is true, the feature is enabled,
otherwise disabled (which is the default). When enabled, and the selected bus address refers to an
<filename>AF_UNIX</filename> socket in the file system which does not exist while the connection attempt is made an
<citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> watch is installed on
it, waiting for the socket to appear. As soon as the socket appears the connection is made. This functionality is
useful in particular in early-boot programs that need to run before the system bus is available, but want to
connect to it the instant it may be connected to.</para>
<para><function>sd_bus_get_watch_bind()</function> may be used to query the current setting of this feature. It
returns zero when the feature is disabled, and positive if enabled.</para>
<para>Note that no timeout is applied while it is waited for the socket to appear. This means that any synchronous
remote operation (such as
<citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>), that is
used on a connection with this feature enabled that is not established yet might block unbounded if the socket is
never created. However, asynchronous remote operations (such as
<citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_add_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
<citerefentry><refentrytitle>sd_bus_request_match_async</refentrytitle><manvolnum>3</manvolnum></citerefentry>) do
not block in this case, and safely enqueue the requested operations to be dispatched the instant the connection is
set up.</para>
<para>Use <citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
determine whether the connection is fully established, i.e. whether the peer socket has been bound, connected to
and authenticated. Use
<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry> to
be notified when the connection is fully established.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The bus connection has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_bus_set_watch_bind()</function> and <function>sd_bus_get_watch_bind()</function> are available as
a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_is_ready</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

8
meson.build
View File

@@ -2556,6 +2556,14 @@ endif
############################################################
meson_check_api_docs_sh = find_program('tools/meson-check-api-docs.sh')
run_target(
'check-api-docs',
depends : [man, libsystemd, libudev],
command : [meson_check_api_docs_sh, libsystemd.full_path(), libudev.full_path()])
############################################################
status = [
'@0@ @1@'.format(meson.project_name(), meson.project_version()),

7
src/basic/def.h
View File

@@ -53,9 +53,10 @@
"/usr/lib/kbd/keymaps/\0"
#endif
#define UNIX_SYSTEM_BUS_ADDRESS "unix:path=/var/run/dbus/system_bus_socket"
#define DEFAULT_SYSTEM_BUS_ADDRESS UNIX_SYSTEM_BUS_ADDRESS
#define UNIX_USER_BUS_ADDRESS_FMT "unix:path=%s/bus"
/* Note that we use the new /run prefix here (instead of /var/run) since we require them to be aliases and that way we
* become independent of /var being mounted */
#define DEFAULT_SYSTEM_BUS_ADDRESS "unix:path=/run/dbus/system_bus_socket"
#define DEFAULT_USER_BUS_ADDRESS_FMT "unix:path=%s/bus"
#define PLYMOUTH_SOCKET { \
.un.sun_family = AF_UNIX, \

55
src/basic/fs-util.c
View File

@@ -315,43 +315,60 @@ int fd_warn_permissions(const char *path, int fd) {
}
int touch_file(const char *path, bool parents, usec_t stamp, uid_t uid, gid_t gid, mode_t mode) {
_cleanup_close_ int fd;
int r;
char fdpath[STRLEN("/proc/self/fd/") + DECIMAL_STR_MAX(int)];
_cleanup_close_ int fd = -1;
int r, ret = 0;
assert(path);
/* Note that touch_file() does not follow symlinks: if invoked on an existing symlink, then it is the symlink
* itself which is updated, not its target
*
* Returns the first error we encounter, but tries to apply as much as possible. */
if (parents)
mkdir_parents(path, 0755);
(void) mkdir_parents(path, 0755);
fd = open(path, O_WRONLY|O_CREAT|O_CLOEXEC|O_NOCTTY,
IN_SET(mode, 0, MODE_INVALID) ? 0644 : mode);
if (fd < 0)
return -errno;
/* Initially, we try to open the node with O_PATH, so that we get a reference to the node. This is useful in
* case the path refers to an existing device or socket node, as we can open it successfully in all cases, and
* won't trigger any driver magic or so. */
fd = open(path, O_PATH|O_CLOEXEC|O_NOFOLLOW);
if (fd < 0) {
if (errno != ENOENT)
return -errno;
if (mode != MODE_INVALID) {
r = fchmod(fd, mode);
if (r < 0)
/* if the node doesn't exist yet, we create it, but with O_EXCL, so that we only create a regular file
* here, and nothing else */
fd = open(path, O_WRONLY|O_CREAT|O_EXCL|O_CLOEXEC, IN_SET(mode, 0, MODE_INVALID) ? 0644 : mode);
if (fd < 0)
return -errno;
}
if (uid != UID_INVALID || gid != GID_INVALID) {
r = fchown(fd, uid, gid);
if (r < 0)
return -errno;
}
/* Let's make a path from the fd, and operate on that. With this logic, we can adjust the access mode,
* ownership and time of the file node in all cases, even if the fd refers to an O_PATH object — which is
* something fchown(), fchmod(), futimensat() don't allow. */
xsprintf(fdpath, "/proc/self/fd/%i", fd);
if (mode != MODE_INVALID)
if (chmod(fdpath, mode) < 0)
ret = -errno;
if (uid_is_valid(uid) || gid_is_valid(gid))
if (chown(fdpath, uid, gid) < 0 && ret >= 0)
ret = -errno;
if (stamp != USEC_INFINITY) {
struct timespec ts[2];
timespec_store(&ts[0], stamp);
ts[1] = ts[0];
r = futimens(fd, ts);
r = utimensat(AT_FDCWD, fdpath, ts, 0);
} else
r = futimens(fd, NULL);
if (r < 0)
r = utimensat(AT_FDCWD, fdpath, NULL, 0);
if (r < 0 && ret >= 0)
return -errno;
return 0;
return ret;
}
int touch(const char *path) {

9
src/basic/io-util.c
View File

@@ -33,6 +33,7 @@ int flush_fd(int fd) {
.fd = fd,
.events = POLLIN,
};
int count = 0;
/* Read from the specified file descriptor, until POLLIN is not set anymore, throwing away everything
* read. Note that some file descriptors (notable IP sockets) will trigger POLLIN even when no data can be read
@@ -52,7 +53,7 @@ int flush_fd(int fd) {
return -errno;
} else if (r == 0)
return 0;
return count;
l = read(fd, buf, sizeof(buf));
if (l < 0) {
@@ -61,11 +62,13 @@ int flush_fd(int fd) {
continue;
if (errno == EAGAIN)
return 0;
return count;
return -errno;
} else if (l == 0)
return 0;
return count;
count += (int) l;
}
}

23
src/basic/socket-label.c
View File

@@ -29,6 +29,7 @@
#include "alloc-util.h"
#include "fd-util.h"
#include "fs-util.h"
#include "log.h"
#include "macro.h"
#include "missing.h"
@@ -51,6 +52,7 @@ int socket_address_listen(
const char *label) {
_cleanup_close_ int fd = -1;
const char *p;
int r, one;
assert(a);
@@ -112,19 +114,23 @@ int socket_address_listen(
if (setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &one, sizeof(one)) < 0)
return -errno;
if (socket_address_family(a) == AF_UNIX && a->sockaddr.un.sun_path[0] != 0) {
p = socket_address_get_path(a);
if (p) {
/* Create parents */
(void) mkdir_parents_label(a->sockaddr.un.sun_path, directory_mode);
(void) mkdir_parents_label(p, directory_mode);
/* Enforce the right access mode for the socket */
RUN_WITH_UMASK(~socket_mode) {
r = mac_selinux_bind(fd, &a->sockaddr.sa, a->size);
if (r == -EADDRINUSE) {
/* Unlink and try again */
unlink(a->sockaddr.un.sun_path);
if (bind(fd, &a->sockaddr.sa, a->size) < 0)
return -errno;
} else if (r < 0)
if (unlink(p) < 0)
return r; /* didn't work, return original error */
r = mac_selinux_bind(fd, &a->sockaddr.sa, a->size);
}
if (r < 0)
return r;
}
} else {
@@ -136,6 +142,11 @@ int socket_address_listen(
if (listen(fd, backlog) < 0)
return -errno;
/* Let's trigger an inotify event on the socket node, so that anyone waiting for this socket to be connectable
* gets notified */
if (p)
(void) touch(p);
r = fd;
fd = -1;

35
src/basic/socket-util.c
View File

@@ -68,7 +68,6 @@ DEFINE_STRING_TABLE_LOOKUP(socket_address_type, int);
int socket_address_parse(SocketAddress *a, const char *s) {
char *e, *n;
unsigned u;
int r;
assert(a);
@@ -78,6 +77,8 @@ int socket_address_parse(SocketAddress *a, const char *s) {
a->type = SOCK_STREAM;
if (*s == '[') {
uint16_t port;
/* IPv6 in [x:.....:z]:p notation */
e = strchr(s+1, ']');
@@ -95,15 +96,12 @@ int socket_address_parse(SocketAddress *a, const char *s) {
return -EINVAL;
e++;
r = safe_atou(e, &u);
r = parse_ip_port(e, &port);
if (r < 0)
return r;
if (u <= 0 || u > 0xFFFF)
return -EINVAL;
a->sockaddr.in6.sin6_family = AF_INET6;
a->sockaddr.in6.sin6_port = htobe16((uint16_t)u);
a->sockaddr.in6.sin6_port = htobe16(port);
a->size = sizeof(struct sockaddr_in6);
} else if (*s == '/') {
@@ -134,12 +132,13 @@ int socket_address_parse(SocketAddress *a, const char *s) {
} else if (startswith(s, "vsock:")) {
/* AF_VSOCK socket in vsock:cid:port notation */
const char *cid_start = s + STRLEN("vsock:");
unsigned port;
e = strchr(cid_start, ':');
if (!e)
return -EINVAL;
r = safe_atou(e+1, &u);
r = safe_atou(e+1, &port);
if (r < 0)
return r;
@@ -152,19 +151,18 @@ int socket_address_parse(SocketAddress *a, const char *s) {
a->sockaddr.vm.svm_cid = VMADDR_CID_ANY;
a->sockaddr.vm.svm_family = AF_VSOCK;
a->sockaddr.vm.svm_port = u;
a->sockaddr.vm.svm_port = port;
a->size = sizeof(struct sockaddr_vm);
} else {
uint16_t port;
e = strchr(s, ':');
if (e) {
r = safe_atou(e+1, &u);
r = parse_ip_port(e + 1, &port);
if (r < 0)
return r;
if (u <= 0 || u > 0xFFFF)
return -EINVAL;
n = strndupa(s, e-s);
/* IPv4 in w.x.y.z:p notation? */
@@ -175,7 +173,7 @@ int socket_address_parse(SocketAddress *a, const char *s) {
if (r > 0) {
/* Gotcha, it's a traditional IPv4 address */
a->sockaddr.in.sin_family = AF_INET;
a->sockaddr.in.sin_port = htobe16((uint16_t)u);
a->sockaddr.in.sin_port = htobe16(port);
a->size = sizeof(struct sockaddr_in);
} else {
unsigned idx;
@@ -189,7 +187,7 @@ int socket_address_parse(SocketAddress *a, const char *s) {
return -EINVAL;
a->sockaddr.in6.sin6_family = AF_INET6;
a->sockaddr.in6.sin6_port = htobe16((uint16_t)u);
a->sockaddr.in6.sin6_port = htobe16(port);
a->sockaddr.in6.sin6_scope_id = idx;
a->sockaddr.in6.sin6_addr = in6addr_any;
a->size = sizeof(struct sockaddr_in6);
@@ -197,21 +195,18 @@ int socket_address_parse(SocketAddress *a, const char *s) {
} else {
/* Just a port */
r = safe_atou(s, &u);
r = parse_ip_port(s, &port);
if (r < 0)
return r;
if (u <= 0 || u > 0xFFFF)
return -EINVAL;
if (socket_ipv6_is_supported()) {
a->sockaddr.in6.sin6_family = AF_INET6;
a->sockaddr.in6.sin6_port = htobe16((uint16_t)u);
a->sockaddr.in6.sin6_port = htobe16(port);
a->sockaddr.in6.sin6_addr = in6addr_any;
a->size = sizeof(struct sockaddr_in6);
} else {
a->sockaddr.in.sin_family = AF_INET;
a->sockaddr.in.sin_port = htobe16((uint16_t)u);
a->sockaddr.in.sin_port = htobe16(port);
a->sockaddr.in.sin_addr.s_addr = INADDR_ANY;
a->size = sizeof(struct sockaddr_in);
}

12
src/basic/socket-util.h
View File

@@ -36,16 +36,26 @@
#include "util.h"
union sockaddr_union {
/* The minimal, abstract version */
struct sockaddr sa;
/* The libc provided version that allocates "enough room" for every protocol */
struct sockaddr_storage storage;
/* Protoctol-specific implementations */
struct sockaddr_in in;
struct sockaddr_in6 in6;
struct sockaddr_un un;
struct sockaddr_nl nl;
struct sockaddr_storage storage;
struct sockaddr_ll ll;
struct sockaddr_vm vm;
/* Ensure there is enough space to store Infiniband addresses */
uint8_t ll_buffer[offsetof(struct sockaddr_ll, sll_addr) + CONST_MAX(ETH_ALEN, INFINIBAND_ALEN)];
/* Ensure there is enough space after the AF_UNIX sun_path for one more NUL byte, just to be sure that the path
* component is always followed by at least one NUL byte. */
uint8_t un_buffer[sizeof(struct sockaddr_un) + 1];
};
typedef struct SocketAddress {

37
src/basic/verbs.c
View File

@@ -30,45 +30,36 @@
#include "verbs.h"
#include "virt.h"
/* Wraps running_in_chroot() which is used in various places,
* but also adds an environment variable check so external processes
* can reliably force this on.
/* Wraps running_in_chroot() which is used in various places, but also adds an environment variable check so external
* processes can reliably force this on.
*/
bool running_in_chroot_or_offline(void) {
int r;
/* Added to support use cases like rpm-ostree, where from %post
* scripts we only want to execute "preset", but not "start"/"restart"
* for example.
/* Added to support use cases like rpm-ostree, where from %post scripts we only want to execute "preset", but
* not "start"/"restart" for example.
*
* See ENVIRONMENT.md for docs.
*/
r = getenv_bool("SYSTEMD_OFFLINE");
if (r < 0)
log_debug_errno(r, "Parsing SYSTEMD_OFFLINE: %m");
else if (r == 0)
return false;
else
return true;
if (r < 0 && r != -ENXIO)
log_debug_errno(r, "Failed to parse $SYSTEMD_OFFLINE: %m");
else if (r >= 0)
return r > 0;
/* We've had this condition check for a long time which basically
* checks for legacy chroot case like Fedora's
* "mock", which is used for package builds. We don't want
* to try to start systemd services there, since without --new-chroot
* we don't even have systemd running, and even if we did, adding
* a concept of background daemons to builds would be an enormous change,
* requiring considering things like how the journal output is handled, etc.
* And there's really not a use case today for a build talking to a service.
/* We've had this condition check for a long time which basically checks for legacy chroot case like Fedora's
* "mock", which is used for package builds. We don't want to try to start systemd services there, since
* without --new-chroot we don't even have systemd running, and even if we did, adding a concept of background
* daemons to builds would be an enormous change, requiring considering things like how the journal output is
* handled, etc. And there's really not a use case today for a build talking to a service.
*
* Note this call itself also looks for a different variable SYSTEMD_IGNORE_CHROOT=1.
*/
r = running_in_chroot();
if (r < 0)
log_debug_errno(r, "running_in_chroot(): %m");
else if (r > 0)
return true;
return false;
return r > 0;
}
int dispatch_verb(int argc, char *argv[], const Verb verbs[], void *userdata) {

23
src/busctl/busctl.c
View File

@@ -62,6 +62,7 @@ static bool arg_expect_reply = true;
static bool arg_auto_start = true;
static bool arg_allow_interactive_authorization = true;
static bool arg_augment_creds = true;
static bool arg_watch_bind = false;
static usec_t arg_timeout = 0;
#define NAME_IS_ACQUIRED INT_TO_PTR(1)
@@ -1735,7 +1736,9 @@ static int help(void) {
" --allow-interactive-authorization=BOOL\n"
" Allow interactive authorization for operation\n"
" --timeout=SECS Maximum time to wait for method call completion\n"
" --augment-creds=BOOL Extend credential data with data read from /proc/$PID\n\n"
" --augment-creds=BOOL Extend credential data with data read from /proc/$PID\n"
" --watch-bind=BOOL Wait for bus AF_UNIX socket to be bound in the file\n"
" system\n\n"
"Commands:\n"
" list List bus names\n"
" status [SERVICE] Show bus service, process or bus owner credentials\n"
@@ -1777,6 +1780,7 @@ static int parse_argv(int argc, char *argv[]) {
ARG_ALLOW_INTERACTIVE_AUTHORIZATION,
ARG_TIMEOUT,
ARG_AUGMENT_CREDS,
ARG_WATCH_BIND,
};
static const struct option options[] = {
@@ -1803,6 +1807,7 @@ static int parse_argv(int argc, char *argv[]) {
{ "allow-interactive-authorization", required_argument, NULL, ARG_ALLOW_INTERACTIVE_AUTHORIZATION },
{ "timeout", required_argument, NULL, ARG_TIMEOUT },
{ "augment-creds",required_argument, NULL, ARG_AUGMENT_CREDS},
{ "watch-bind", required_argument, NULL, ARG_WATCH_BIND },
{},
};
@@ -1953,6 +1958,16 @@ static int parse_argv(int argc, char *argv[]) {
arg_augment_creds = !!r;
break;
case ARG_WATCH_BIND:
r = parse_boolean(optarg);
if (r < 0) {
log_error("Failed to parse --watch-bind= parameter.");
return r;
}
arg_watch_bind = !!r;
break;
case '?':
return -EINVAL;
@@ -2051,6 +2066,12 @@ int main(int argc, char *argv[]) {
goto finish;
}
r = sd_bus_set_watch_bind(bus, arg_watch_bind);
if (r < 0) {
log_error_errno(r, "Failed to set watch-bind setting to '%s': %m", yes_no(arg_watch_bind));
goto finish;
}
if (arg_address)
r = sd_bus_set_address(bus, arg_address);
else {

Some files were not shown because too many files have changed in this diff Show More