man/sd_event_source_set_destroy_callback.xml

   1 <?xml version='1.0'?>
   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 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   6
   7 <refentry id="sd_event_source_set_destroy_callback"
   8           xmlns:xi="http://www.w3.org/2001/XInclude">
   9
  10   <refentryinfo>
  11     <title>sd_event_source_set_destroy_callback</title>
  12     <productname>systemd</productname>
  13   </refentryinfo>
  14
  15   <refmeta>
  16     <refentrytitle>sd_event_source_set_destroy_callback</refentrytitle>
  17     <manvolnum>3</manvolnum>
  18   </refmeta>
  19
  20   <refnamediv>
  21     <refname>sd_event_source_set_destroy_callback</refname>
  22     <refname>sd_event_source_get_destroy_callback</refname>
  23     <refname>sd_event_destroy_t</refname>
  24
  25     <refpurpose>Define the callback function for resource cleanup.</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv>
  29     <funcsynopsis>
  30       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  31
  32       <funcprototype>
  33         <funcdef>typedef int (*<function>sd_event_destroy_t</function>)</funcdef>
  34         <paramdef>void *<parameter>userdata</parameter></paramdef>
  35       </funcprototype>
  36
  37       <funcprototype>
  38         <funcdef>int <function>sd_event_source_set_destroy_callback</function></funcdef>
  39         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  40         <paramdef>sd_event_destroy_t <parameter>callback</parameter></paramdef>
  41       </funcprototype>
  42
  43       <funcprototype>
  44         <funcdef>int <function>sd_event_source_get_destroy_callback</function></funcdef>
  45         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  46         <paramdef>sd_event_destroy_t *<parameter>callback</parameter></paramdef>
  47       </funcprototype>
  48
  49     </funcsynopsis>
  50   </refsynopsisdiv>
  51
  52   <refsect1>
  53     <title>Description</title>
  54
  55     <para><function>sd_event_source_set_destroy_callback()</function> sets <parameter>callback</parameter> as the
  56     callback function to be called right before the event source object <parameter>source</parameter> is
  57     deallocated. The <parameter>userdata</parameter> pointer from the event source object will be passed as the
  58     <parameter>userdata</parameter> parameter. This pointer can be set by an argument to the constructor functions, see
  59     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, or directly,
  60     see
  61     <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  62     This callback function is called even if <parameter>userdata</parameter> is <constant>NULL</constant>. Note that
  63     this callback is invoked at a time where the event source object itself is already invalidated, and executing
  64     operations or taking new references to the event source object is not permissible.</para>
  65
  66     <para><function>sd_event_source_get_destroy_callback()</function> returns the current callback
  67     for <parameter>source</parameter> in the <parameter>callback</parameter> parameter.</para>
  68   </refsect1>
  69
  70   <refsect1>
  71     <title>Return Value</title>
  72
  73     <para>On success, <function>sd_event_source_set_destroy_callback()</function> returns 0 or a positive integer. On
  74     failure, it returns a negative errno-style error code.</para>
  75
  76     <para><function>sd_event_source_get_destroy_callback()</function> returns positive if the destroy callback function
  77     is set, 0 if not. On failure, returns a negative errno-style error code.</para>
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Errors</title>
  82
  83     <para>Returned errors may indicate the following problems:</para>
  84
  85     <variablelist>
  86       <varlistentry>
  87         <term><constant>-EINVAL</constant></term>
  88
  89         <listitem><para>The <parameter>source</parameter> parameter is <constant>NULL</constant>.</para></listitem>
  90       </varlistentry>
  91     </variablelist>
  92   </refsect1>
  93
  94   <xi:include href="libsystemd-pkgconfig.xml" />
  95
  96   <refsect1>
  97     <title>See Also</title>
  98
  99     <para>
 100       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 101       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 102       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 103       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 104       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 105       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 106       <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 107       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 108       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 109     </para>
 110   </refsect1>
 111
 112 </refentry>