diff options
Diffstat (limited to 'man/sd_bus_new.xml')
| -rw-r--r-- | man/sd_bus_new.xml | 57 |
1 files changed, 42 insertions, 15 deletions
diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml index 207291408e..1bc011d70a 100644 --- a/man/sd_bus_new.xml +++ b/man/sd_bus_new.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> +<?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -23,6 +23,8 @@ <refname>sd_bus_ref</refname> <refname>sd_bus_unref</refname> <refname>sd_bus_unrefp</refname> + <refname>sd_bus_flush_close_unref</refname> + <refname>sd_bus_flush_close_unrefp</refname> <refpurpose>Create a new bus object and create or destroy references to it</refpurpose> </refnamediv> @@ -48,7 +50,17 @@ <funcprototype> <funcdef>void <function>sd_bus_unrefp</function></funcdef> - <paramdef>sd_bus **<parameter>bus</parameter></paramdef> + <paramdef>sd_bus **<parameter>busp</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>sd_bus *<function>sd_bus_flush_close_unref</function></funcdef> + <paramdef>sd_bus *<parameter>bus</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>sd_bus_flush_close_unrefp</function></funcdef> + <paramdef>sd_bus **<parameter>busp</parameter></paramdef> </funcprototype> </funcsynopsis> </refsynopsisdiv> @@ -96,19 +108,33 @@ block is left:</para> <programlisting>{ - __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; - int r; - … - r = sd_bus_default(&bus); - if (r < 0) - fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); - … + __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL; + int r; + … + r = sd_bus_default(&bus); + if (r < 0) + fprintf(stderr, "Failed to allocate bus: %s\n", strerror(-r)); + … }</programlisting> - <para><function>sd_bus_ref()</function>, - <function>sd_bus_unref()</function> and - <function>sd_bus_unrefp()</function> execute no operation if the - passed in bus object is <constant>NULL</constant>.</para> + <para><function>sd_bus_ref()</function> and <function>sd_bus_unref()</function> + execute no operation if the passed in bus object address is + <constant>NULL</constant>. <function>sd_bus_unrefp()</function> will first + dereference its argument, which must not be <constant>NULL</constant>, and will + execute no operation if <emphasis>that</emphasis> is <constant>NULL</constant>. + </para> + + <para><function>sd_bus_flush_close_unref()</function> is similar to <function>sd_bus_unref()</function>, but first + executes <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry> as well + as <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry>, ensuring that + any pending messages are properly flushed out before the reference to the connection is dropped and possibly the + object freed. This call is particularly useful immediately before exiting from a program as it ensures that any + pending outgoing messages are written out, and unprocessed but queued incoming messages released before the + connection is terminated and released.</para> + + <para><function>sd_bus_flush_close_unrefp()</function> is similar to + <function>sd_bus_flush_close_unref()</function>, but may be used in GCC's and LLVM's Clean-up Variable Attribute, + see above.</para> </refsect1> <refsect1> @@ -121,7 +147,7 @@ <para><function>sd_bus_ref()</function> always returns the argument. </para> - <para><function>sd_bus_unref()</function> always returns + <para><function>sd_bus_unref()</function> and <function>sd_bus_flush_close_unref()</function> always return <constant>NULL</constant>.</para> </refsect1> @@ -150,7 +176,8 @@ <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_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> + <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_bus_close</refentrytitle><manvolnum>3</manvolnum></citerefentry> </para> </refsect1> |