Merge pull request #2052 from poettering/export-cleanup

Make gcc cleanup helper calls public in most of our sd-xyz APIs

5 files changed, 140 insertions, 12 deletions

diff --git a/man/sd_bus_creds_new_from_pid.xml b/man/sd_bus_creds_new_from_pid.xml
index 84dd509744..082f7b67db 100644
--- a/man/sd_bus_creds_new_from_pid.xml
+++ b/man/sd_bus_creds_new_from_pid.xml
@@ -48,6 +48,7 @@
     <refname>sd_bus_creds_get_augmented_mask</refname>
     <refname>sd_bus_creds_ref</refname>
     <refname>sd_bus_creds_unref</refname>
+    <refname>sd_bus_creds_unrefp</refname>
 
     <refpurpose>Retrieve credentials object for the specified PID</refpurpose>
   </refnamediv>
@@ -82,6 +83,11 @@
         <funcdef>sd_bus_creds *<function>sd_bus_creds_unref</function></funcdef>
         <paramdef>sd_bus_creds *<parameter>c</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>sd_bus_creds_unrefp</function></funcdef>
+        <paramdef>sd_bus_creds **<parameter>c</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
 
     <para>
@@ -235,6 +241,21 @@
 
     <para><function>sd_bus_creds_unref()</function> destroys a reference
     to <parameter>c</parameter>.</para>
+
+    <para><function>sd_bus_creds_unrefp()</function> is similar to
+    <function>sd_bus_creds_unref()</function> but takes a pointer to a
+    pointer to an <type>sd_bus_creds</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.</para>
+
+    <para><function>sd_bus_creds_ref()</function>,
+    <function>sd_bus_creds_unref()</function> and
+    <function>sd_bus_creds_unrefp()</function> execute no operation if
+    the passed in bus credentials object is
+    <constant>NULL</constant>.</para>
+
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_bus_new.xml b/man/sd_bus_new.xml
index e1cab6e567..d281b5dd44 100644
--- a/man/sd_bus_new.xml
+++ b/man/sd_bus_new.xml
@@ -46,6 +46,7 @@
     <refname>sd_bus_new</refname>
     <refname>sd_bus_ref</refname>
     <refname>sd_bus_unref</refname>
+    <refname>sd_bus_unrefp</refname>
 
     <refpurpose>Create a new bus object and create or destroy references to it</refpurpose>
   </refnamediv>
@@ -68,6 +69,11 @@
         <funcdef>sd_bus *<function>sd_bus_unref</function></funcdef>
         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
       </funcprototype>
+
+      <funcprototype>
+        <funcdef>void <function>sd_bus_unrefp</function></funcdef>
+        <paramdef>sd_bus **<parameter>bus</parameter></paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -93,14 +99,40 @@
     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>.</para>
+    <para><function>sd_bus_ref()</function> increases the reference
+    counter of <parameter>bus</parameter> by one.</para>
 
-    <para><function>sd_bus_unref()</function> destroys a reference to
-    <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
+    <para><function>sd_bus_unref()</function> decreases the reference
+    counter of <parameter>bus</parameter> by one. Once the reference
+    count has dropped to zero, <parameter>bus</parameter> is destroyed
+    and cannot be used anymore, so further calls to
+    <function>sd_bus_ref()</function> or
     <function>sd_bus_unref()</function> are illegal.</para>
+
+    <para><function>sd_bus_unrefp()</function> is similar to
+    <function>sd_bus_unref()</function> but takes a pointer to a
+    pointer to an <type>sd_bus</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 a bus object that is freed automatically as the code
+    block is left:</para>
+
+    <programlisting>{
+        __attribute__((cleanup(sd_bus_unrefp)) sd_bus *bus = NULL;
+        int r;
+        …
+        r = sd_bus_default(&amp;bus);
+        if (r &lt; 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>
   </refsect1>
 
   <refsect1>
@@ -110,10 +142,10 @@
     positive integer. On failure, it returns a negative errno-style
     error code.</para>
 
-    <para><function>sd_bus_ref</function> always returns the argument.
+    <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> always returns
     <constant>NULL</constant>.</para>
   </refsect1>
 
diff --git a/man/sd_event_new.xml b/man/sd_event_new.xml
index 3356faa899..2c23b00a8c 100644
--- 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>
 
@@ -80,6 +81,11 @@
       </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>
         <paramdef>pid_t *<parameter>tid</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
diff --git a/man/sd_event_source_unref.xml b/man/sd_event_source_unref.xml
index 579ec47e8e..2c4d450763 100644
--- a/man/sd_event_source_unref.xml
+++ b/man/sd_event_source_unref.xml
@@ -44,6 +44,7 @@
 
   <refnamediv>
     <refname>sd_event_source_unref</refname>
+    <refname>sd_event_source_unrefp</refname>
     <refname>sd_event_source_ref</refname>
 
     <refpurpose>Increase or decrease event source reference counters</refpurpose>
@@ -59,6 +60,11 @@
       </funcprototype>
 
       <funcprototype>
+        <funcdef>void <function>sd_event_source_unrefp</function></funcdef>
+        <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
         <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef>
         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
       </funcprototype>
@@ -80,12 +86,23 @@
     the reference counter reaches zero it is removed from its event loop
     object and destroyed.</para>
 
+    <para><function>sd_event_source_unrefp()</function> is similar to
+    <function>sd_event_source_unref()</function> but takes a pointer to a
+    pointer to an <type>sd_event_source</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.</para>
+
     <para><function>sd_event_source_ref()</function> may be used
     to increase by one the reference counter of the event source object
     specified as <parameter>source</parameter>.</para>
 
-    <para>Both functions execute no operation if the passed event
-    source object is <constant>NULL</constant>.</para>
+    <para><function>sd_event_source_unref()</function>,
+    <function>sd_bus_creds_unrefp()</function> and
+    <function>sd_bus_creds_ref()</function> execute no operation if
+    the passed event source object is
+    <constant>NULL</constant>.</para>
 
     <para>Note that event source objects stay alive and may be
     dispatched as long as they have a reference counter greater than
diff --git a/man/sd_login_monitor_new.xml b/man/sd_login_monitor_new.xml
index db21d70252..5625ab9207 100644
--- a/man/sd_login_monitor_new.xml
+++ b/man/sd_login_monitor_new.xml
@@ -45,6 +45,7 @@
   <refnamediv>
     <refname>sd_login_monitor_new</refname>
     <refname>sd_login_monitor_unref</refname>
+    <refname>sd_login_monitor_unrefp</refname>
     <refname>sd_login_monitor_flush</refname>
     <refname>sd_login_monitor_get_fd</refname>
     <refname>sd_login_monitor_get_events</refname>
@@ -69,6 +70,11 @@
       </funcprototype>
 
       <funcprototype>
+        <funcdef>void <function>sd_login_monitor_unrefp</function></funcdef>
+        <paramdef>sd_login_monitor **<parameter>m</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
         <funcdef>int <function>sd_login_monitor_flush</function></funcdef>
         <paramdef>sd_login_monitor *<parameter>m</parameter></paramdef>
       </funcprototype>
@@ -121,6 +127,26 @@
     descriptor returned by
     <function>sd_login_monitor_get_fd()</function>.</para>
 
+    <para><function>sd_login_monitor_unrefp()</function> is similar to
+    <function>sd_login_monitor_unref()</function> but takes a pointer
+    to a pointer to an <type>sd_login_monitor</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 a login monitor object that is freed automatically as the
+    code block is left:</para>
+
+    <programlisting>{
+        __attribute__((cleanup(sd_login_monitor_unrefp)) sd_login_monitor *m = NULL;
+        int r;
+        …
+        r = sd_login_monitor_default(&amp;m);
+        if (r &lt; 0)
+                fprintf(stderr, "Failed to allocate login monitor object: %s\n", strerror(-r));
+        …
+}</programlisting>
+
     <para><function>sd_login_monitor_flush()</function> may be used to
     reset the wakeup state of the monitor object. Whenever an event
     causes the monitor to wake up the event loop via the file
@@ -128,6 +154,11 @@
     state. If this call is not invoked, the file descriptor will
     immediately wake up the event loop again.</para>
 
+    <para><function>sd_login_monitor_unref()</function> and
+    <function>sd_login_monitor_unrefp()</function> execute no
+    operation if the passed in monitor object is
+    <constant>NULL</constant>.</para>
+
     <para><function>sd_login_monitor_get_fd()</function> may be used
     to retrieve the file descriptor of the monitor object that may be
     integrated in an application defined event loop, based around