man: various documentation improvements for sd-bus
This commit is contained in:
parent
ff99498535
commit
850df10ac1
|
@ -109,26 +109,30 @@
|
||||||
<title>Description</title>
|
<title>Description</title>
|
||||||
|
|
||||||
<para><function>sd_bus_default()</function> acquires a bus
|
<para><function>sd_bus_default()</function> acquires a bus
|
||||||
connection object to the user bus when invoked in user context or
|
connection object to the user bus when invoked in user context, or
|
||||||
to the system bus otherwise. The connection object is associated
|
to the system bus otherwise. The connection object is associated
|
||||||
to the calling thread. Each time the function is invoked from the
|
to the calling thread. Each time the function is invoked from the
|
||||||
same thread the same object is returned, but its reference count
|
same thread the same object is returned, but its reference count
|
||||||
increased by one, as long as at least one reference is kept. When
|
is increased by one, as long as at least one reference is
|
||||||
the last reference to the connection is dropped (using the
|
kept. When the last reference to the connection is dropped (using
|
||||||
<function>sd_bus_unref()</function> call), the connection is
|
the
|
||||||
terminated. Note that the connection is not automatically
|
<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
terminated when the associated thread ends. It is important to
|
call), the connection is terminated. Note that the connection is
|
||||||
drop the last reference to the bus connection explicitly before
|
not automatically terminated when the associated thread ends. It
|
||||||
the thread ends or otherwise the connection will be leaked.</para>
|
is important to drop the last reference to the bus connection
|
||||||
|
explicitly before the thread ends or otherwise the connection will
|
||||||
|
be leaked.</para>
|
||||||
|
|
||||||
<para><function>sd_bus_default_user()</function> returns a user
|
<para><function>sd_bus_default_user()</function> returns a user
|
||||||
bus connection object associated to the calling thread.
|
bus connection object associated to the calling thread.
|
||||||
<function>sd_bus_default_system()</function> is similar, but
|
<function>sd_bus_default_system()</function> is similar, but
|
||||||
connects to the system bus.</para>
|
connects to the system bus. Note that
|
||||||
|
<function>sd_bus_default()</function> is identical to these two
|
||||||
|
calls, depending on the execution context.</para>
|
||||||
|
|
||||||
<para><function>sd_bus_open()</function> creates a new,
|
<para><function>sd_bus_open()</function> creates a new,
|
||||||
independent bus connection to the user bus when invoked in user
|
independent bus connection to the user bus when invoked in user
|
||||||
context or the system bus
|
context, or the system bus
|
||||||
otherwise. <function>sd_bus_open_user()</function> is similar, but
|
otherwise. <function>sd_bus_open_user()</function> is similar, but
|
||||||
connects only to the user bus.
|
connects only to the user bus.
|
||||||
<function>sd_bus_open_system()</function> does the same, but
|
<function>sd_bus_open_system()</function> does the same, but
|
||||||
|
@ -162,8 +166,10 @@
|
||||||
|
|
||||||
<para><function>sd_bus_open_system_remote()</function> connects to
|
<para><function>sd_bus_open_system_remote()</function> connects to
|
||||||
the system bus on the specified <parameter>host</parameter> using
|
the system bus on the specified <parameter>host</parameter> using
|
||||||
SSH. <parameter>host</parameter> consists of an optional user name
|
<citerefentry
|
||||||
followed by the <literal>@</literal> symbol, and the hostname.
|
project='die-net'><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <parameter>host</parameter>
|
||||||
|
consists of an optional user name followed by the
|
||||||
|
<literal>@</literal> symbol, and the hostname.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para><function>sd_bus_open_system_container()</function> connects
|
<para><function>sd_bus_open_system_container()</function> connects
|
||||||
|
@ -171,7 +177,18 @@
|
||||||
where <parameter>machine</parameter> is the name of a local
|
where <parameter>machine</parameter> is the name of a local
|
||||||
container. See
|
container. See
|
||||||
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||||
for more information about "machines".</para>
|
for more information about the "machine" concept. Note that
|
||||||
|
connections into local containers are only available to privileged
|
||||||
|
processes at this time.</para>
|
||||||
|
|
||||||
|
<para>These calls allocate a bus connection object and initiate
|
||||||
|
the connection ot a well-known bus of some form. An alternative to
|
||||||
|
using these high-level calls is to create an unconnected bus
|
||||||
|
object with
|
||||||
|
<citerefentry><refentrytitle>sd_bus_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
and to connect it with
|
||||||
|
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||||
|
</para>
|
||||||
|
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
@ -185,8 +202,8 @@
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Reference ownership</title>
|
<title>Reference ownership</title>
|
||||||
<para>The functions <function>sd_bus_open_user()</function>,
|
<para>The functions <function>sd_bus_open()</function>,
|
||||||
<function>sd_bus_open()</function>,
|
<function>sd_bus_open_user()</function>,
|
||||||
<function>sd_bus_open_system()</function>,
|
<function>sd_bus_open_system()</function>,
|
||||||
<function>sd_bus_open_system_remote()</function>, and
|
<function>sd_bus_open_system_remote()</function>, and
|
||||||
<function>sd_bus_open_system_machine()</function> return a new
|
<function>sd_bus_open_system_machine()</function> return a new
|
||||||
|
|
|
@ -70,7 +70,7 @@
|
||||||
<funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
|
<funcdef>int <function>sd_bus_negotiate_creds</function></funcdef>
|
||||||
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
|
||||||
<paramdef>int <parameter>b</parameter></paramdef>
|
<paramdef>int <parameter>b</parameter></paramdef>
|
||||||
<paramdef>uint64_t <parameter>flags</parameter></paramdef>
|
<paramdef>uint64_t <parameter>mask</parameter></paramdef>
|
||||||
</funcprototype>
|
</funcprototype>
|
||||||
</funcsynopsis>
|
</funcsynopsis>
|
||||||
</refsynopsisdiv>
|
</refsynopsisdiv>
|
||||||
|
@ -81,10 +81,11 @@
|
||||||
<para><function>sd_bus_negotiate_fds()</function> controls whether
|
<para><function>sd_bus_negotiate_fds()</function> controls whether
|
||||||
file descriptor passing shall be negotiated for the specified bus
|
file descriptor passing shall be negotiated for the specified bus
|
||||||
connection. It takes a bus object and a boolean, which, when true,
|
connection. It takes a bus object and a boolean, which, when true,
|
||||||
enables file descriptor passing, and, when false, disables it. Note
|
enables file descriptor passing, and, when false, disables
|
||||||
that not all transports and servers support file descriptor
|
it. Note that not all transports and servers support file
|
||||||
passing. To find out whether file descriptor passing is available
|
descriptor passing. In particular, networked transports generally
|
||||||
after negotiation, use
|
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>
|
<citerefentry><refentrytitle>sd_bus_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
|
and pass <constant>SD_BUS_TYPE_UNIX_FD</constant>. Note that file
|
||||||
descriptor passing is always enabled for both sending and
|
descriptor passing is always enabled for both sending and
|
||||||
|
@ -101,34 +102,44 @@
|
||||||
<para><function>sd_bus_negotiate_timestamps()</function> controls
|
<para><function>sd_bus_negotiate_timestamps()</function> controls
|
||||||
whether implicit sender timestamps shall be attached automatically
|
whether implicit sender timestamps shall be attached automatically
|
||||||
to all incoming messages. Takes a bus object and a boolean, which,
|
to all incoming messages. Takes a bus object and a boolean, which,
|
||||||
when true, enables timestamping, and, when false, disables it. If
|
when true, enables timestamping, and, when false, disables it.
|
||||||
this is disabled,
|
Use
|
||||||
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<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_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
fail with <constant>-ENODATA</constant> on incoming messages. Note
|
to query the timestamps of incoming messages. If negotiation is
|
||||||
that not all transports support timestamping of messages. On local
|
disabled or not supported these calls will fail with
|
||||||
transports, the timestamping is applied by the kernel and cannot
|
<constant>-ENODATA</constant>. Note that not all transports
|
||||||
be manipulated by userspace. By default, message timestamping is
|
support timestamping of messages. Specifically, timestamping is
|
||||||
not negotiated for all connections.</para>
|
only available on the kdbus transport, but not on dbus1. The
|
||||||
|
timestamping is applied by the kernel and cannot be manipulated by
|
||||||
|
userspace. By default, message timestamping is not negotiated for
|
||||||
|
connections.</para>
|
||||||
|
|
||||||
<para><function>sd_bus_negotiate_creds()</function> controls
|
<para><function>sd_bus_negotiate_creds()</function> controls
|
||||||
whether implicit sender credentials shall be attached
|
whether and which implicit sender credentials shall be attached
|
||||||
automatically to all incoming messages. Takes a bus object, a
|
automatically to all incoming messages. Takes a bus object, a
|
||||||
boolean indicating whether to enable or disable the credential
|
boolean indicating whether to enable or disable the credential
|
||||||
parts encoded in the bit mask value argument. Note that not all
|
parts encoded in the bit mask value argument. Note that not all
|
||||||
transports support attaching sender credentials to messages, or do
|
transports support attaching sender credentials to messages, or do
|
||||||
not support all types of sender credential parameters, or might
|
not support all types of sender credential parameters, or might
|
||||||
suppress them under certain circumstances for individual
|
suppress them under certain circumstances for individual
|
||||||
messages. On local transports, the sender credentials are attached
|
messages. Specifically, implicit sender credentials on messages
|
||||||
by the kernel and cannot be manipulated by userspace. By default,
|
are only fully supported on kdbus transports, and dbus1 only
|
||||||
no sender credentials are attached.</para>
|
supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender
|
||||||
|
credentials are attached by the kernel and cannot be manipulated
|
||||||
|
by userspace, and are thus 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>The <function>sd_bus_negotiate_fds()</function> function may
|
<para>The <function>sd_bus_negotiate_fds()</function> function may
|
||||||
be called only before the connection has been started with
|
be called only before the connection has been started with
|
||||||
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
|
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Both
|
||||||
<function>sd_bus_negotiate_timestamp()</function> and
|
<function>sd_bus_negotiate_timestamp()</function> and
|
||||||
<function>sd_bus_negotiate_creds()</function> also may be called
|
<function>sd_bus_negotiate_creds()</function> may also be called
|
||||||
after a connection has been set up. Note that when operating on a
|
after a connection has been set up. Note that when operating on a
|
||||||
connection that is shared between multiple components of the same
|
connection that is shared between multiple components of the same
|
||||||
program (for example via
|
program (for example via
|
||||||
|
@ -163,7 +174,7 @@
|
||||||
<refsect1>
|
<refsect1>
|
||||||
<title>Notes</title>
|
<title>Notes</title>
|
||||||
|
|
||||||
<para><function>sd_bus_negotiate_fs()</function> and the other
|
<para><function>sd_bus_negotiate_fds()</function> and the other
|
||||||
functions described here are available as a shared library, which
|
functions described here are available as a shared library, which
|
||||||
can be compiled and linked to with the
|
can be compiled and linked to with the
|
||||||
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||||
|
@ -179,6 +190,8 @@
|
||||||
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_message_can_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<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>,
|
||||||
<citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_message_get_creds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||||
</para>
|
</para>
|
||||||
|
|
|
@ -77,7 +77,21 @@
|
||||||
<para><function>sd_bus_new()</function> creates a new bus
|
<para><function>sd_bus_new()</function> creates a new bus
|
||||||
object. This object is reference-counted, and will be destroyed
|
object. This object is reference-counted, and will be destroyed
|
||||||
when all references are gone. Initially, the caller of this
|
when all references are gone. Initially, the caller of this
|
||||||
function owns the sole reference.</para>
|
function owns the sole reference. The bus object will not be
|
||||||
|
connected to any bus initially. To connect it to a bus, make sure
|
||||||
|
to set an address with
|
||||||
|
<citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
or a related call, and then start the connection with
|
||||||
|
<citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
|
||||||
|
|
||||||
|
<para>In most cases it's a better idea to invoke
|
||||||
|
<citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
|
or related calls instead of the more low-level
|
||||||
|
<function>sd_bus_new()</function> and
|
||||||
|
<function>sd_bus_start()</function>. The higher-level calls not
|
||||||
|
only allocate a bus object but also start the connection to a
|
||||||
|
well-known bus in a single function invocation.</para>
|
||||||
|
|
||||||
<para><function>sd_bus_ref()</function> creates a new reference to
|
<para><function>sd_bus_ref()</function> creates a new reference to
|
||||||
<parameter>bus</parameter>. This bus object will not be destroyed
|
<parameter>bus</parameter>. This bus object will not be destroyed
|
||||||
|
@ -135,10 +149,10 @@
|
||||||
<para>
|
<para>
|
||||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
<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_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
||||||
<citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
|
||||||
<citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
<citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
<citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
<citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
|
||||||
|
<citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue