1<?xml version='1.0'?> 2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> 5 6<refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_source_unref</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_source_unref</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_source_unref</refname> 20 <refname>sd_event_source_unrefp</refname> 21 <refname>sd_event_source_ref</refname> 22 <refname>sd_event_source_disable_unref</refname> 23 <refname>sd_event_source_disable_unrefp</refname> 24 25 <refpurpose>Increase or decrease event source reference counters</refpurpose> 26 </refnamediv> 27 28 <refsynopsisdiv> 29 <funcsynopsis> 30 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 31 32 <funcprototype> 33 <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef> 34 <paramdef>sd_event_source *<parameter>source</parameter></paramdef> 35 </funcprototype> 36 37 <funcprototype> 38 <funcdef>void <function>sd_event_source_unrefp</function></funcdef> 39 <paramdef>sd_event_source **<parameter>source</parameter></paramdef> 40 </funcprototype> 41 42 <funcprototype> 43 <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef> 44 <paramdef>sd_event_source *<parameter>source</parameter></paramdef> 45 </funcprototype> 46 47 <funcprototype> 48 <funcdef>sd_event_source* <function>sd_event_source_disable_unref</function></funcdef> 49 <paramdef>sd_event_source *<parameter>source</parameter></paramdef> 50 </funcprototype> 51 52 <funcprototype> 53 <funcdef>void <function>sd_event_source_disable_unrefp</function></funcdef> 54 <paramdef>sd_event_source **<parameter>source</parameter></paramdef> 55 </funcprototype> 56 </funcsynopsis> 57 </refsynopsisdiv> 58 59 <refsect1> 60 <title>Description</title> 61 62 <para><function>sd_event_source_unref()</function> may be used to decrement by one the internal reference 63 counter of the event source object specified as <parameter>source</parameter>. The reference counter is 64 initially set to one, when the event source is created with calls such as 65 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry> or 66 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When 67 the reference counter reaches zero, the object is detached from the event loop object and destroyed. 68 </para> 69 70 <para><function>sd_event_source_unrefp()</function> is similar to 71 <function>sd_event_source_unref()</function> but takes a pointer to a 72 pointer to an <type>sd_event_source</type> object. This call is useful in 73 conjunction with GCC's and LLVM's <ulink 74 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up 75 Variable Attribute</ulink>. Note that this function is defined as 76 inline function.</para> 77 78 <para><function>sd_event_source_ref()</function> may be used to increase by one the internal reference 79 counter of the event source object specified as <parameter>source</parameter>.</para> 80 81 <para><function>sd_event_source_unref()</function>, 82 <function>sd_bus_creds_unrefp()</function> and 83 <function>sd_bus_creds_ref()</function> execute no operation if 84 the passed event source object is 85 <constant>NULL</constant>.</para> 86 87 <para>Note that event source objects stay alive and may be dispatched as long as they have a reference 88 counter greater than zero. In order to drop a reference of an event source and make sure the associated 89 event source handler function is not called anymore it is recommended to combine a call of 90 <function>sd_event_source_unref()</function> with a prior call to 91 <function>sd_event_source_set_enabled()</function> with <constant>SD_EVENT_OFF</constant> or call 92 <function>sd_event_source_disable_unref()</function>, see below.</para> 93 94 <para><function>sd_event_source_disable_unref()</function> combines a call to 95 <function>sd_event_source_set_enabled()</function> with <constant>SD_EVENT_OFF</constant> with 96 <function>sd_event_source_unref()</function>. This ensures that the source is disabled before the local 97 reference to it is lost. The <parameter>source</parameter> parameter is allowed to be 98 <constant>NULL</constant>.</para> 99 100 <para><function>sd_event_source_disable_unrefp()</function> is similar to 101 <function>sd_event_source_unrefp()</function>, but in addition disables the source first. This call is 102 useful in conjunction with GCC's and LLVM's 103 <ulink url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up Variable 104 Attribute</ulink>. Note that this function is defined as inline function.</para> 105 </refsect1> 106 107 <refsect1> 108 <title>Return Value</title> 109 110 <para><function>sd_event_source_unref()</function> and 111 <function>sd_event_source_disable_unref()</function> always return <constant>NULL</constant>. 112 <function>sd_event_source_ref()</function> always returns the event source object passed in.</para> 113 </refsect1> 114 115 <xi:include href="libsystemd-pkgconfig.xml" /> 116 117 <refsect1> 118 <title>See Also</title> 119 120 <para> 121 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 122 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 123 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 124 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 125 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 126 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 127 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 128 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry> 129 </para> 130 </refsect1> 131 132</refentry> 133