chiark / gitweb /
man: bring machinectl man page up-to-date
[elogind.git] / man / sd_event_new.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 2014 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_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 object 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 have exactly either zero or one default event loop
104     objects associated, but never more.</para>
105
106     <para><function>sd_event_ref()</function> increases the reference
107     count of the specified event loop object by one.</para>
108
109     <para><function>sd_event_unref()</function> decreases the
110     reference count of the specified event loop object by one. If
111     the count hits zero, the 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 each keeps 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     <constant>NULL</constant>.</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><constant>-ENOMEM</constant></term>
142
143         <listitem><para>Not enough memory to allocate the object.</para></listitem>
144       </varlistentry>
145
146       <varlistentry>
147         <term><constant>-EMFILE</constant></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 project='die-net'><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>