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_ref</refname>
  48
  49     <refpurpose>Increase or decrease event source reference counters</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <funcsynopsis>
  54       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  55
  56       <funcprototype>
  57         <funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef>
  58         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  59       </funcprototype>
  60
  61       <funcprototype>
  62         <funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef>
  63         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  64       </funcprototype>
  65
  66     </funcsynopsis>
  67   </refsynopsisdiv>
  68
  69   <refsect1>
  70     <title>Description</title>
  71
  72     <para><function>sd_event_source_unref()</function> may be used to
  73     decrement by one the reference counter of the event source object
  74     specified as <parameter>source</parameter>. The reference counter
  75     is initially set to one, when the event source is created with calls
  76     such as
  77     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  78     or
  79     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When
  80     the reference counter reaches zero it is removed from its event loop
  81     object and destroyed.</para>
  82
  83     <para><function>sd_event_source_ref()</function> may be used
  84     to increase by one the reference counter of the event source object
  85     specified as <parameter>source</parameter>.</para>
  86
  87     <para>Both functions execute no operation if the passed event
  88     source object is <constant>NULL</constant>.</para>
  89
  90     <para>Note that event source objects stay alive and may be
  91     dispatched as long as they have a reference counter greater than
  92     zero. In order to drop a reference of an event source and make
  93     sure the associated event source handler function is not called
  94     anymore it is recommended to combine a call of
  95     <function>sd_event_source_unref()</function> with a prior call to
  96     <function>sd_event_source_set_enabled()</function> with
  97     <constant>SD_EVENT_OFF</constant>.</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Return Value</title>
 102
 103     <para><function>sd_event_source_unref()</function> always returns
 104     <constant>NULL</constant>.
 105     <function>sd_event_source_ref()</function> always returns the
 106     event source object passed in.</para>
 107   </refsect1>
 108
 109   <xi:include href="libsystemd-pkgconfig.xml" />
 110
 111   <refsect1>
 112     <title>See Also</title>
 113
 114     <para>
 115       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 116       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 117       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 118       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 119       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 120       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 121       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 122     </para>
 123   </refsect1>
 124
 125 </refentry>