man: various documentation improvements for sd-bus
This commit is contained in:
Lennart Poettering
parent
ff99498535
commit
850df10ac1
|
|
@ -109,26 +109,30 @@
|
|||
<title>Description</title>
|
||||
|
||||
<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 calling thread. Each time the function is invoked from the
|
||||
same thread the same object is returned, but its reference count
|
||||
increased by one, as long as at least one reference is kept. When
|
||||
the last reference to the connection is dropped (using the
|
||||
<function>sd_bus_unref()</function> call), the connection is
|
||||
terminated. Note that the connection is not automatically
|
||||
terminated when the associated thread ends. It is important to
|
||||
drop the last reference to the bus connection explicitly before
|
||||
the thread ends or otherwise the connection will be leaked.</para>
|
||||
is increased by one, as long as at least one reference is
|
||||
kept. When the last reference to the connection is dropped (using
|
||||
the
|
||||
<citerefentry><refentrytitle>sd_bus_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
call), the connection is terminated. Note that the connection is
|
||||
not automatically terminated when the associated thread ends. It
|
||||
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
|
||||
bus connection object associated to the calling thread.
|
||||
<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,
|
||||
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
|
||||
connects only to the user bus.
|
||||
<function>sd_bus_open_system()</function> does the same, but
|
||||
|
|
@ -162,8 +166,10 @@
|
|||
|
||||
<para><function>sd_bus_open_system_remote()</function> connects to
|
||||
the system bus on the specified <parameter>host</parameter> using
|
||||
SSH. <parameter>host</parameter> consists of an optional user name
|
||||
followed by the <literal>@</literal> symbol, and the hostname.
|
||||
<citerefentry
|
||||
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><function>sd_bus_open_system_container()</function> connects
|
||||
|
|
@ -171,7 +177,18 @@
|
|||
where <parameter>machine</parameter> is the name of a local
|
||||
container. See
|
||||
<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>
|
||||
|
||||
|
|
@ -185,8 +202,8 @@
|
|||
|
||||
<refsect1>
|
||||
<title>Reference ownership</title>
|
||||
<para>The functions <function>sd_bus_open_user()</function>,
|
||||
<function>sd_bus_open()</function>,
|
||||
<para>The functions <function>sd_bus_open()</function>,
|
||||
<function>sd_bus_open_user()</function>,
|
||||
<function>sd_bus_open_system()</function>,
|
||||
<function>sd_bus_open_system_remote()</function>, and
|
||||
<function>sd_bus_open_system_machine()</function> return a new
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@
|
|||
<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>flags</parameter></paramdef>
|
||||
<paramdef>uint64_t <parameter>mask</parameter></paramdef>
|
||||
</funcprototype>
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
|
@ -81,10 +81,11 @@
|
|||
<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. To find out whether file descriptor passing is available
|
||||
after negotiation, use
|
||||
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
|
||||
|
|
@ -101,34 +102,44 @@
|
|||
<para><function>sd_bus_negotiate_timestamps()</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. If
|
||||
this is disabled,
|
||||
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>
|
||||
fail with <constant>-ENODATA</constant> on incoming messages. Note
|
||||
that not all transports support timestamping of messages. On local
|
||||
transports, the timestamping is applied by the kernel and cannot
|
||||
be manipulated by userspace. By default, message timestamping is
|
||||
not negotiated for all connections.</para>
|
||||
to query the timestamps of incoming messages. If negotiation is
|
||||
disabled or not supported these calls will fail with
|
||||
<constant>-ENODATA</constant>. Note that not all transports
|
||||
support timestamping of messages. Specifically, timestamping is
|
||||
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
|
||||
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
|
||||
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. On local transports, the sender credentials are attached
|
||||
by the kernel and cannot be manipulated by userspace. By default,
|
||||
no sender credentials are attached.</para>
|
||||
messages. Specifically, implicit sender credentials on messages
|
||||
are only fully supported on kdbus transports, and dbus1 only
|
||||
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
|
||||
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> 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
|
||||
connection that is shared between multiple components of the same
|
||||
program (for example via
|
||||
|
|
@ -163,7 +174,7 @@
|
|||
<refsect1>
|
||||
<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
|
||||
can be compiled and linked to with the
|
||||
<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_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_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>systemd.busname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -77,7 +77,21 @@
|
|||
<para><function>sd_bus_new()</function> creates a new bus
|
||||
object. This object is reference-counted, and will be destroyed
|
||||
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
|
||||
<parameter>bus</parameter>. This bus object will not be destroyed
|
||||
|
|
@ -135,10 +149,10 @@
|
|||
<para>
|
||||
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</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_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>
|
||||
</refsect1>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue