sd_event_new.xml revision b975b0d514321f169b3c4599a8ea92e13741b4e4
3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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">
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Lennart Poettering
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering<refentry id="sd_event_new" conditional="ENABLE_KDBUS">
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refentryinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </authorgroup>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refentryinfo>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refentrytitle>sd_event_new</refentrytitle>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refpurpose>Acquire and release an event loop object</refpurpose>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <refsynopsisdiv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcsynopsis>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
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 <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 <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 <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 </funcsynopsis>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </refsynopsisdiv>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_new()</function> allocates a new event
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering loop object. The event loop object is returned in the
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <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
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek dropped, the object is freed.</para>
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
b8bde11658366290521e3d03316378b482600323Jan Engelhardt allocated yet for the thread. After use, drop the returned
a6ad1458e8baf913e9ee377c52863b927d7a2638Thomas Hindoe Paaboel Andersen reference with <function>sd_event_unref()</function>. When the
b8bde11658366290521e3d03316378b482600323Jan Engelhardt 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
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek thread. All threads have exactly either zero or one default event loop
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek objects associated, but never more.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_ref()</function> increases the reference
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek count of the specified event loop object by one.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para><function>sd_event_unref()</function> decreases the
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek reference count of the specified event loop object by one. If
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek the count hits zero, the 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
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <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
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek 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
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek freed as each keeps a reference to it.</para>
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
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek <constant>NULL</constant>.</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <para>Returned errors may indicate the following problems:</para>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <variablelist>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-ENOMEM</constant></term>
bfe6c07e1b6bd8bf63d662c60fb333a003bb97a1Zbigniew Jędrzejewski-Szmek <listitem><para>Not enough memory to allocate the object.</para></listitem>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <varlistentry>
8474b70c3a3842cdf3d51f331dd117ab6421f6d0Zbigniew Jędrzejewski-Szmek <term><constant>-EMFILE</constant></term>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering <listitem><para>The maximum number of event loops has been allocated.</para></listitem>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </varlistentry>
faae655de3cdbed4be1d472b01ce0c4d81e905edLennart Poettering </variablelist>
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
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
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>