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