sd_event_new.xml revision 681eb9cf2b831293a4f3d4c48a748d2e4a25d69e
d657c51f14601d0235434ffb78cf6ac0f27cc83cLennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
220a21d38f675eb835f5758e3d23e896573aa5eaLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering<!ENTITY % entities SYSTEM "custom-entities.ent" >
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering This file is part of systemd.
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering Copyright 2014 Lennart Poettering
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering systemd is free software; you can redistribute it and/or modify it
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering under the terms of the GNU Lesser General Public License as published by
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering (at your option) any later version.
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering systemd is distributed in the hope that it will be useful, but
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering Lesser General Public License for more details.
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering You should have received a copy of the GNU Lesser General Public License
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering<refentry id="sd_event_new" conditional="ENABLE_KDBUS">
4ef6e535e30c67d4ff34b2ca785e555dbaeac14eKay Sievers <refentryinfo>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </authorgroup>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </refentryinfo>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <refentrytitle>sd_event_new</refentrytitle>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <refpurpose>Acquire and release an event loop object</refpurpose>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <refsynopsisdiv>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcsynopsis>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcdef>int <function>sd_event_new</function></funcdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <paramdef>sd_bus **<parameter>event</parameter></paramdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcdef>int <function>sd_event_default</function></funcdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <paramdef>sd_bus **<parameter>event</parameter></paramdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcprototype>
4ef6e535e30c67d4ff34b2ca785e555dbaeac14eKay Sievers <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <paramdef>sd_bus *<parameter>event</parameter></paramdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <paramdef>sd_bus *<parameter>event</parameter></paramdef>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </funcprototype>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </funcsynopsis>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering </refsynopsisdiv>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <para><function>sd_event_new()</function> allocates a new event
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering loop object. The event loop object is returned in the
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <parameter>event</parameter> parameter. After use, drop
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering the returned reference with
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <function>sd_event_unref()</function>. When the last reference is
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering dropped, the object is freed.</para>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <para><function>sd_event_default()</function> acquires a reference
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering to the default event loop object of the calling thread, possibly
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering allocating a new object if no default event loop object has been
4ef6e535e30c67d4ff34b2ca785e555dbaeac14eKay Sievers allocated yet for the thread. After use, drop the returned
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering reference with <function>sd_event_unref()</function>. When the
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering last reference is dropped, the event loop is freed. If this
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering function is called while the object returned from a previous call
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering from the same thread is still referenced, the same object is
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering returned again, but the reference is increased by one. It is
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering recommended to use this call instead of
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <function>sd_event_new()</function> in order to share event loop
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering objects between various components that are dispatched in the same
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering thread. All threads have exactly either zero or one default event loop
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering objects associated, but never more.</para>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <para><function>sd_event_ref()</function> increases the reference
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering count of the specified event loop object by one.</para>
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <para><function>sd_event_unref()</function> decreases the
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering reference count of the specified event loop object by one. If
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering the count hits zero, the object is freed. Note that it
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering is freed regardless of whether it is the default event loop object for a
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering thread or not. This means that allocating an event loop with
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <function>sd_event_default()</function>, then releasing it, and
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering then acquiring a new one with
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering <function>sd_event_default()</function> will result in two
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering distinct objects. Note that in order to free an event loop object,
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering all remaining event sources of the event loop also need to be
699b6b3491dc265ead79602404ad67ccdacae302Lennart Poettering freed as each keeps a reference to it.</para>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <para>On success, <function>sd_event_new()</function> and
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <function>sd_event_default()</function> return 0 or a positive
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering integer. On failure, they return a negative errno-style error
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering code. <function>sd_event_ref()</function> always returns a pointer
67dd87c51b1ba254dc6a0eeae41762aace40addaLennart Poettering to the event loop object passed
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering in. <function>sd_event_unref()</function> always returns
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <para>Returned errors may indicate the following problems:</para>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <variablelist>
ed28905eecf631916f03edd0a7dfad8b0a177990Kay Sievers <varlistentry>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <term><constant>-ENOMEM</constant></term>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <listitem><para>Not enough memory to allocate the object.</para></listitem>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering </varlistentry>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <varlistentry>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering </varlistentry>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering </variablelist>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <para><function>sd_event_new()</function> and the other functions
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering described here are available as a shared library, which can be
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering compiled and linked to with the
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
43c71255b3db02916f4f70afa18bab196c6f4a45Lennart Poettering <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>