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_new" xmlns:xi="http://www.w3.org/2001/XInclude"> 7 8 <refentryinfo> 9 <title>sd_event_new</title> 10 <productname>systemd</productname> 11 </refentryinfo> 12 13 <refmeta> 14 <refentrytitle>sd_event_new</refentrytitle> 15 <manvolnum>3</manvolnum> 16 </refmeta> 17 18 <refnamediv> 19 <refname>sd_event_new</refname> 20 <refname>sd_event_default</refname> 21 <refname>sd_event_ref</refname> 22 <refname>sd_event_unref</refname> 23 <refname>sd_event_unrefp</refname> 24 <refname>sd_event_get_tid</refname> 25 <refname>sd_event</refname> 26 27 <refpurpose>Acquire and release an event loop object</refpurpose> 28 </refnamediv> 29 30 <refsynopsisdiv> 31 <funcsynopsis> 32 <funcsynopsisinfo>#include <systemd/sd-event.h></funcsynopsisinfo> 33 34 <funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo> 35 36 <funcprototype> 37 <funcdef>int <function>sd_event_new</function></funcdef> 38 <paramdef>sd_event **<parameter>event</parameter></paramdef> 39 </funcprototype> 40 41 <funcprototype> 42 <funcdef>int <function>sd_event_default</function></funcdef> 43 <paramdef>sd_event **<parameter>event</parameter></paramdef> 44 </funcprototype> 45 46 <funcprototype> 47 <funcdef>sd_event *<function>sd_event_ref</function></funcdef> 48 <paramdef>sd_event *<parameter>event</parameter></paramdef> 49 </funcprototype> 50 51 <funcprototype> 52 <funcdef>sd_event *<function>sd_event_unref</function></funcdef> 53 <paramdef>sd_event *<parameter>event</parameter></paramdef> 54 </funcprototype> 55 56 <funcprototype> 57 <funcdef>void <function>sd_event_unrefp</function></funcdef> 58 <paramdef>sd_event **<parameter>event</parameter></paramdef> 59 </funcprototype> 60 61 <funcprototype> 62 <funcdef>int <function>sd_event_get_tid</function></funcdef> 63 <paramdef>sd_event *<parameter>event</parameter></paramdef> 64 <paramdef>pid_t *<parameter>tid</parameter></paramdef> 65 </funcprototype> 66 67 </funcsynopsis> 68 </refsynopsisdiv> 69 70 <refsect1> 71 <title>Description</title> 72 73 <para><function>sd_event_new()</function> allocates a new event 74 loop object. The event loop object is returned in the 75 <parameter>event</parameter> parameter. After use, drop 76 the returned reference with 77 <function>sd_event_unref()</function>. When the last reference is 78 dropped, the object is freed.</para> 79 80 <para><function>sd_event_default()</function> acquires a reference 81 to the default event loop object of the calling thread, possibly 82 allocating a new object if no default event loop object has been 83 allocated yet for the thread. After use, drop the returned 84 reference with <function>sd_event_unref()</function>. When the 85 last reference is dropped, the event loop is freed. If this 86 function is called while the object returned from a previous call 87 from the same thread is still referenced, the same object is 88 returned again, but the reference is increased by one. It is 89 recommended to use this call instead of 90 <function>sd_event_new()</function> in order to share event loop 91 objects between various components that are dispatched in the same 92 thread. All threads have exactly either zero or one default event loop 93 objects associated, but never more.</para> 94 95 <para>After allocating an event loop object, add event sources to 96 it with 97 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 98 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 99 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 100 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 101 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 102 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 103 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry> or 104 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 105 and then execute the event loop using 106 <citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> 107 108 <para><function>sd_event_ref()</function> increases the reference 109 count of the specified event loop object by one.</para> 110 111 <para><function>sd_event_unref()</function> decreases the 112 reference count of the specified event loop object by one. If 113 the count hits zero, the object is freed. Note that it 114 is freed regardless of whether it is the default event loop object for a 115 thread or not. This means that allocating an event loop with 116 <function>sd_event_default()</function>, then releasing it, and 117 then acquiring a new one with 118 <function>sd_event_default()</function> will result in two 119 distinct objects. Note that, in order to free an event loop object, 120 all remaining event sources of the event loop also need to be 121 freed as each keeps a reference to it.</para> 122 123 <para><function>sd_event_unrefp()</function> is similar to 124 <function>sd_event_unref()</function> but takes a pointer to a 125 pointer to an <type>sd_event</type> object. This call is useful in 126 conjunction with GCC's and LLVM's <ulink 127 url="https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html">Clean-up 128 Variable Attribute</ulink>. Note that this function is defined as 129 inline function. Use a declaration like the following, 130 in order to allocate an event loop object that is freed 131 automatically as the code block is left:</para> 132 133 <programlisting>{ 134 __attribute__((cleanup(sd_event_unrefp))) sd_event *event = NULL; 135 int r; 136 … 137 r = sd_event_default(&event); 138 if (r < 0) 139 fprintf(stderr, "Failed to allocate event loop: %s\n", strerror(-r)); 140 … 141}</programlisting> 142 143 <para><function>sd_event_ref()</function>, 144 <function>sd_event_unref()</function> and 145 <function>sd_event_unrefp()</function> execute no operation if the 146 passed in event loop object is <constant>NULL</constant>.</para> 147 148 <para><function>sd_event_get_tid()</function> retrieves the thread 149 identifier ("TID") of the thread the specified event loop object 150 is associated with. This call is only supported for event loops 151 allocated with <function>sd_event_default()</function>, and 152 returns the identifier for the thread the event loop is the 153 default event loop of. See <citerefentry 154 project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> 155 for more information on thread identifiers.</para> 156 </refsect1> 157 158 <refsect1> 159 <title>Return Value</title> 160 161 <para>On success, <function>sd_event_new()</function>, <function>sd_event_default()</function> and 162 <function>sd_event_get_tid()</function> return 0 or a positive integer. On failure, they return a 163 negative errno-style error code. <function>sd_event_ref()</function> always returns a pointer to the 164 event loop object passed in. <function>sd_event_unref()</function> always returns 165 <constant>NULL</constant>.</para> 166 167 <refsect2> 168 <title>Errors</title> 169 170 <para>Returned errors may indicate the following problems:</para> 171 172 <variablelist> 173 <varlistentry> 174 <term><constant>-ENOMEM</constant></term> 175 176 <listitem><para>Not enough memory to allocate the object.</para></listitem> 177 </varlistentry> 178 179 <varlistentry> 180 <term><constant>-EMFILE</constant></term> 181 182 <listitem><para>The maximum number of event loops has been allocated.</para></listitem> 183 184 </varlistentry> 185 186 <varlistentry> 187 <term><constant>-ENXIO</constant></term> 188 189 <listitem><para><function>sd_event_get_tid()</function> was invoked on an event loop object that 190 was not allocated with <function>sd_event_default()</function>.</para></listitem> 191 </varlistentry> 192 193 </variablelist> 194 </refsect2> 195 </refsect1> 196 197 <xi:include href="libsystemd-pkgconfig.xml" /> 198 199 <refsect1> 200 <title>See Also</title> 201 202 <para> 203 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 204 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 205 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 206 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 207 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 208 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 209 <citerefentry><refentrytitle>sd_event_add_inotify</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 210 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 211 <citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 212 <citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry> 213 </para> 214 </refsect1> 215 216</refentry> 217