tree-wide: expose "p"-suffix unref calls in public APIs to make gcc cleanup easy

[thirdparty/systemd.git] / man / sd_event_new.xml

diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml
index 3356faa89943102b8777541820dedd09cc5c69b3..2c23b00a8c7bd80c2293d8ce37d6aadd7650b9b4 100644 (file)
--- a/man/sd_event_new.xml
+++ b/man/sd_event_new.xml
@@ -47,6 +47,7 @@
     <refname>sd_event_default</refname>
     <refname>sd_event_ref</refname>
     <refname>sd_event_unref</refname>
+    <refname>sd_event_unrefp</refname>
     <refname>sd_event_get_tid</refname>
     <refname>sd_event</refname>
 
@@ -79,6 +80,11 @@
         <paramdef>sd_event *<parameter>event</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef>void <function>sd_event_unrefp</function></funcdef>
+        <paramdef>sd_event **<parameter>event</parameter></paramdef>
+      </funcprototype>
+
       <funcprototype>
         <funcdef>int <function>sd_event_get_tid</function></funcdef>
         <paramdef>sd_event *<parameter>event</parameter></paramdef>
@@ -139,8 +145,29 @@
     all remaining event sources of the event loop also need to be
     freed as each keeps a reference to it.</para>
 
-    <para>Both <function>sd_event_ref()</function> and
-    <function>sd_event_unref()</function> execute no operation if the
+    <para><function>sd_event_unrefp()</function> is similar to
+    <function>sd_event_unref()</function> but takes a pointer to a
+    pointer to an <type>sd_event</type> object. This call is useful in
+    conjunction with GCC's and LLVM's <ulink
+    url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
+    Variable Attribute</ulink>. Note that this function is defined as
+    inline function. Use a declaration like the following,
+    in order to allocate an event loop object that is freed
+    automatically as the code block is left:</para>
+
+    <programlisting>{
+        __attribute__((cleanup(sd_event_unrefp)) sd_event *event = NULL;
+        int r;
+        …
+        r = sd_event_default(&amp;event);
+        if (r &lt; 0)
+                fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r));
+        …
+}</programlisting>
+
+    <para><function>sd_event_ref()</function>,
+    <function>sd_event_unref()</function> and
+    <function>sd_event_unrefp()</function> execute no operation if the
     passed in event loop object is <constant>NULL</constant>.</para>
 
     <para><function>sd_event_get_tid()</function> retrieves the thread