diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/sd_bus_creds_new_from_pid.xml | 21 | ||||
| -rw-r--r-- | man/sd_bus_new.xml | 48 | ||||
| -rw-r--r-- | man/sd_event_new.xml | 31 | ||||
| -rw-r--r-- | man/sd_event_source_unref.xml | 21 | ||||
| -rw-r--r-- | man/sd_login_monitor_new.xml | 31 |
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(&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> </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(&event); + if (r < 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(&m); + if (r < 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 |