]> git.proxmox.com Git - systemd.git/blame - man/sd_event_new.xml
Imported Upstream version 214
[systemd.git] / man / sd_event_new.xml
CommitLineData
60f067b4
JS
1<?xml version='1.0'?> <!--*-nxml-*-->
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<!--
6This file is part of systemd.
7
8Copyright 2014 Lennart Poettering
9
10systemd is free software; you can redistribute it and/or modify it
11under the terms of the GNU Lesser General Public License as published by
12the Free Software Foundation; either version 2.1 of the License, or
13(at your option) any later version.
14
15systemd is distributed in the hope that it will be useful, but
16WITHOUT ANY WARRANTY; without even the implied warranty of
17MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18Lesser General Public License for more details.
19
20You should have received a copy of the GNU Lesser General Public License
21along with systemd; If not, see <http://www.gnu.org/licenses/>.
22-->
23
24<refentry id="sd_event_new" conditional="ENABLE_KDBUS">
25
26 <refentryinfo>
27 <title>sd_event_new</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_new</refentrytitle>
42 <manvolnum>3</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>sd_event_new</refname>
47 <refname>sd_event_default</refname>
48 <refname>sd_event_ref</refname>
49 <refname>sd_event_unref</refname>
50
51 <refpurpose>Acquire and release an event loop object</refpurpose>
52 </refnamediv>
53
54 <refsynopsisdiv>
55 <funcsynopsis>
56 <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
57
58 <funcprototype>
59 <funcdef>int <function>sd_event_new</function></funcdef>
60 <paramdef>sd_bus **<parameter>event</parameter></paramdef>
61 </funcprototype>
62
63 <funcprototype>
64 <funcdef>int <function>sd_event_default</function></funcdef>
65 <paramdef>sd_bus **<parameter>event</parameter></paramdef>
66 </funcprototype>
67
68 <funcprototype>
69 <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
70 <paramdef>sd_bus *<parameter>event</parameter></paramdef>
71 </funcprototype>
72
73 <funcprototype>
74 <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
75 <paramdef>sd_bus *<parameter>event</parameter></paramdef>
76 </funcprototype>
77
78 </funcsynopsis>
79 </refsynopsisdiv>
80
81 <refsect1>
82 <title>Description</title>
83
84 <para><function>sd_event_new()</function> allocates a new event
85 loop object. The event loop object is returned in the
86 <parameter>event</parameter> parameter. After use, drop
87 the returned reference with
88 <function>sd_event_unref()</function>. When the last reference is
89 dropped, the event loop is freed.</para>
90
91 <para><function>sd_event_default()</function> acquires a reference
92 to the default event loop object of the calling thread, possibly
93 allocating a new object if no default event loop object has been
94 allocated yet for the thread. After use, drop the returned
95 reference with <function>sd_event_unref()</function>. When the
96 last reference is dropped, the event loop is freed. If this
97 function is called while the object returned from a previous call
98 from the same thread is still referenced, the same object is
99 returned again, but the reference is increased by one. It is
100 recommended to use this call instead of
101 <function>sd_event_new()</function> in order to share event loop
102 objects between various components that are dispatched in the same
103 thread. All threads either have exactly zero or one default event loop
104 associated, but never more.</para>
105
106 <para><function>sd_event_ref()</function> increases the reference
107 counter of the specified event loop object by one.</para>
108
109 <para><function>sd_event_unref()</function> decreases the
110 reference counter of the specified event loop object by one. If
111 the counter hits zero, the event loop object is freed. Note that it
112 is freed regardless of whether it is the default event loop object for a
113 thread or not. This means that allocating an event loop with
114 <function>sd_event_default()</function>, then releasing it, and
115 then acquiring a new one with
116 <function>sd_event_default()</function> will result in two
117 distinct objects. Note that, in order to free an event loop object,
118 all remaining event sources of the event loop also need to be
119 freed as they each keep a reference to it.</para>
120 </refsect1>
121
122 <refsect1>
123 <title>Return Value</title>
124
125 <para>On success, <function>sd_event_new()</function> and
126 <function>sd_event_default()</function> return 0 or a positive
127 integer. On failure, they return a negative errno-style error
128 code. <function>sd_event_ref()</function> always returns a pointer
129 to the event loop object passed
130 in. <function>sd_event_unref()</function> always returns
131 NULL.</para>
132 </refsect1>
133
134 <refsect1>
135 <title>Errors</title>
136
137 <para>Returned errors may indicate the following problems:</para>
138
139 <variablelist>
140 <varlistentry>
141 <term><varname>-ENOMEM</varname></term>
142
143 <listitem><para>Not enough memory to allocate object</para></listitem>
144 </varlistentry>
145
146 <varlistentry>
147 <term><varname>-EMFILE</varname></term>
148
149 <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
150
151 </varlistentry>
152 </variablelist>
153 </refsect1>
154
155 <refsect1>
156 <title>Notes</title>
157
158 <para><function>sd_event_new()</function> and the other functions
159 described here are available as a shared library, which can be
160 compiled and linked to with the
161 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
162 file.</para>
163 </refsect1>
164
165 <refsect1>
166 <title>See Also</title>
167
168 <para>
169 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
170 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
175 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
176 <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
177 <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
178 </para>
179 </refsect1>
180
181</refentry>