sd_event_new.xml revision dca348bcbb462305864526c587495a14a76bfcde
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering<?xml version='1.0'?> <!--*-nxml-*-->
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering<!--
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart PoetteringThis file is part of systemd.
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart PoetteringCopyright 2014 Lennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poetteringsystemd is free software; you can redistribute it and/or modify it
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poetteringunder the terms of the GNU Lesser General Public License as published by
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poetteringthe Free Software Foundation; either version 2.1 of the License, or
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering(at your option) any later version.
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poetteringsystemd is distributed in the hope that it will be useful, but
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart PoetteringWITHOUT ANY WARRANTY; without even the implied warranty of
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart PoetteringMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart PoetteringLesser General Public License for more details.
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart PoetteringYou should have received a copy of the GNU Lesser General Public License
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poetteringalong with systemd; If not, see <http://www.gnu.org/licenses/>.
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering-->
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering<refentry id="sd_event_new" conditional="ENABLE_KDBUS">
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refentryinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <title>sd_event_new</title>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <productname>systemd</productname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <authorgroup>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <author>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <contrib>Developer</contrib>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <firstname>Lennart</firstname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <surname>Poettering</surname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <email>lennart@poettering.net</email>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </author>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </authorgroup>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refentryinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refmeta>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refentrytitle>sd_event_new</refentrytitle>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <manvolnum>3</manvolnum>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refmeta>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refnamediv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refname>sd_event_new</refname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refname>sd_event_default</refname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refname>sd_event_ref</refname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refname>sd_event_unref</refname>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refpurpose>Acquire and release an event loop object</refpurpose>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refnamediv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsynopsisdiv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcsynopsis>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcdef>int <function>sd_event_new</function></funcdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <paramdef>sd_bus **<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcdef>int <function>sd_event_default</function></funcdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <paramdef>sd_bus **<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <paramdef>sd_bus *<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <paramdef>sd_bus *<parameter>event</parameter></paramdef>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcprototype>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </funcsynopsis>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsynopsisdiv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <title>Description</title>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_new()</function> allocates a new event
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering loop object. The event loop object is returned in the
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <parameter>event</parameter> parameter. After use drop
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering the returned reference with
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_unref()</function>. When the last reference is
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering dropped the event loop is freed.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_default()</function> acquires a reference
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering to the default event loop object of the calling thread, possibly
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering allocating a new object if no default event loop object has been
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering allocated yet for the thread. After use drop the returned
a6ad1458e8baf913e9ee377c52863b927d7a2638Thomas Hindoe Paaboel Andersen reference with <function>sd_event_unref()</function>. When the
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering last reference is dropped the event loop is freed. If this
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering function is called while the object returned from a previous call
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering from the same thread is still referenced, the same object is
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering returned again, but the reference is increased by one. It is
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering recommended to use this call instead of
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_new()</function> in order to share event loop
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering objects between various components that are dispatched in the same
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering thread. All threads either have no or one default event loops
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering associated, but never more.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_ref()</function> increases the reference
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering counter of the specified event loop object by one.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_unref()</function> decreases the
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering reference counter of the specified event loop object by one. If
a6ad1458e8baf913e9ee377c52863b927d7a2638Thomas Hindoe Paaboel Andersen the counter hits zero the event loop object is freed. Note that it
dca348bcbb462305864526c587495a14a76bfcdeJan Engelhardt is freed regardless of whether it is the default event loop object for a
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering thread or not. This means that allocating an event loop with
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_default()</function>, then releasing it and
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering then acquiring a new one with
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_default()</function> will result in two
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering distinct objects. Note that in order to free an event loop object
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering all remaining event sources of the event loop also need to be
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering freed as they each keep a reference to it.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <title>Return Value</title>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para>On success, <function>sd_event_new()</function> and
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <function>sd_event_default()</function> return 0 or a positive
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering integer. On failure, they return a negative errno-style error
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering code. <function>sd_event_ref()</function> always returns a pointer
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering to the event loop object passed
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering in. <function>sd_event_unref()</function> always returns
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering NULL.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <title>Errors</title>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para>Returned errors may indicate the following problems:</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <variablelist>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <term><varname>-ENOMEM</varname></term>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <listitem><para>Not enough memory to allocate object</para></listitem>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <term><varname>-EMFILE</varname></term>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </variablelist>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <title>Notes</title>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_new()</function> and the other functions
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering described here are available as a shared library, which can be
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering compiled and linked to with the
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering file.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <title>See Also</title>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsect1>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering</refentry>