man/sd_event_source_unref.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2015 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude">
  25
  26   <refentryinfo>
  27     <title>sd_event_source_unref</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>sd_event_source_unref</refentrytitle>
  42     <manvolnum>3</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>sd_event_source_unref</refname>
  47     <refname>sd_event_source_unrefp</refname>
  48     <refname>sd_event_source_ref</refname>
  49
  50     <refpurpose>Increase or decrease event source reference counters</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <funcsynopsis>
  55       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  56
  57       <funcprototype>
  58         <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef>
  59         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  60       </funcprototype>
  61
  62       <funcprototype>
  63         <funcdef>void <function>sd_event_source_unrefp</function></funcdef>
  64         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef>
  69         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  70       </funcprototype>
  71
  72     </funcsynopsis>
  73   </refsynopsisdiv>
  74
  75   <refsect1>
  76     <title>Description</title>
  77
  78     <para><function>sd_event_source_unref()</function> may be used to
  79     decrement by one the reference counter of the event source object
  80     specified as <parameter>source</parameter>. The reference counter
  81     is initially set to one, when the event source is created with calls
  82     such as
  83     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  84     or
  85     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When
  86     the reference counter reaches zero it is removed from its event loop
  87     object and destroyed.</para>
  88
  89     <para><function>sd_event_source_unrefp()</function> is similar to
  90     <function>sd_event_source_unref()</function> but takes a pointer to a
  91     pointer to an <type>sd_event_source</type> object. This call is useful in
  92     conjunction with GCC's and LLVM's <ulink
  93     url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up
  94     Variable Attribute</ulink>. Note that this function is defined as
  95     inline function.</para>
  96
  97     <para><function>sd_event_source_ref()</function> may be used
  98     to increase by one the reference counter of the event source object
  99     specified as <parameter>source</parameter>.</para>
 100
 101     <para><function>sd_event_source_unref()</function>,
 102     <function>sd_bus_creds_unrefp()</function> and
 103     <function>sd_bus_creds_ref()</function> execute no operation if
 104     the passed event source object is
 105     <constant>NULL</constant>.</para>
 106
 107     <para>Note that event source objects stay alive and may be
 108     dispatched as long as they have a reference counter greater than
 109     zero. In order to drop a reference of an event source and make
 110     sure the associated event source handler function is not called
 111     anymore it is recommended to combine a call of
 112     <function>sd_event_source_unref()</function> with a prior call to
 113     <function>sd_event_source_set_enabled()</function> with
 114     <constant>SD_EVENT_OFF</constant>.</para>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>Return Value</title>
 119
 120     <para><function>sd_event_source_unref()</function> always returns
 121     <constant>NULL</constant>.
 122     <function>sd_event_source_ref()</function> always returns the
 123     event source object passed in.</para>
 124   </refsect1>
 125
 126   <xi:include href="libsystemd-pkgconfig.xml" />
 127
 128   <refsect1>
 129     <title>See Also</title>
 130
 131     <para>
 132       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 133       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 134       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 135       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 136       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 137       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 138       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 139     </para>
 140   </refsect1>
 141
 142 </refentry>