diff options
Diffstat (limited to 'man/sd_bus_new.xml')
| -rw-r--r-- | man/sd_bus_new.xml | 34 |
1 files changed, 23 insertions, 11 deletions
diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 5c65b9a2fe..aff2ed2e83 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -77,18 +77,30 @@ <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 and the bus object will not be + connected to any bus. 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 - until <function>sd_bus_unref()</function> has been called as many - times plus once more. Once the reference count has dropped to - zero, <parameter>bus</parameter> cannot be used anymore, so - further calls to <function>sd_bus_ref()</function> or - <function>sd_bus_unref()</function> are illegal.</para> + <parameter>bus</parameter>.</para> <para><function>sd_bus_unref()</function> destroys a reference to - <parameter>bus</parameter>.</para> + <parameter>bus</parameter>. Once the reference count has dropped + to zero, <parameter>bus</parameter> cannot be used anymore, so + further calls to <function>sd_bus_ref()</function> or + <function>sd_bus_unref()</function> are illegal.</para> </refsect1> <refsect1> @@ -135,10 +147,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> |