shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

man: fully document sd-event interfaces

Browse Source 
This completes the set of man pages for sd-event and contains some minor
other fixes for other man pages too.

The sd_event_set_name(3) man page is renamed to
sd_event_source_set_description(3), which is the correct name of the
concept today.
This commit is contained in:
Lennart Poettering 2015-11-19 23:38:54 +01:00
parent 0be6c2f617
commit dc83f27a7c
26 changed files with 3073 additions and 499 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
Makefile-man.am
View File

@ -26,6 +26,7 @@ MANPAGES += \
man/os-release.5 \
man/sd-bus-errors.3 \
man/sd-daemon.3 \
man/sd-event.3 \
man/sd-id128.3 \
man/sd-journal.3 \
man/sd_booted.3 \
@ -47,12 +48,23 @@ MANPAGES += \
man/sd_bus_request_name.3 \
man/sd_event_add_child.3 \
man/sd_event_add_defer.3 \
man/sd_event_add_io.3 \
man/sd_event_add_signal.3 \
man/sd_event_add_time.3 \
man/sd_event_exit.3 \
man/sd_event_get_fd.3 \
man/sd_event_new.3 \
man/sd_event_now.3 \
man/sd_event_run.3 \
man/sd_event_set_name.3 \
man/sd_event_set_watchdog.3 \
man/sd_event_source_get_event.3 \
man/sd_event_source_get_pending.3 \
man/sd_event_source_set_description.3 \
man/sd_event_source_set_enabled.3 \
man/sd_event_source_set_prepare.3 \
man/sd_event_source_set_priority.3 \
man/sd_event_source_set_userdata.3 \
man/sd_event_source_unref.3 \
man/sd_event_wait.3 \
man/sd_id128_get_machine.3 \
man/sd_id128_randomize.3 \
@ -199,6 +211,19 @@ MANPAGES_ALIAS += \
man/SD_DEBUG.3 \
man/SD_EMERG.3 \
man/SD_ERR.3 \
man/SD_EVENT_ARMED.3 \
man/SD_EVENT_EXITING.3 \
man/SD_EVENT_FINISHED.3 \
man/SD_EVENT_INITIAL.3 \
man/SD_EVENT_OFF.3 \
man/SD_EVENT_ON.3 \
man/SD_EVENT_ONESHOT.3 \
man/SD_EVENT_PENDING.3 \
man/SD_EVENT_PREPARING.3 \
man/SD_EVENT_PRIORITY_IDLE.3 \
man/SD_EVENT_PRIORITY_IMPORTANT.3 \
man/SD_EVENT_PRIORITY_NORMAL.3 \
man/SD_EVENT_RUNNING.3 \
man/SD_ID128_CONST_STR.3 \
man/SD_ID128_FORMAT_STR.3 \
man/SD_ID128_FORMAT_VAL.3 \
@ -295,21 +320,41 @@ MANPAGES_ALIAS += \
man/sd_bus_ref.3 \
man/sd_bus_release_name.3 \
man/sd_bus_unref.3 \
man/sd_event.3 \
man/sd_event_add_exit.3 \
man/sd_event_add_post.3 \
man/sd_event_child_handler_t.3 \
man/sd_event_default.3 \
man/sd_event_dispatch.3 \
man/sd_event_get_name.3 \
man/sd_event_get_exit_code.3 \
man/sd_event_get_state.3 \
man/sd_event_get_tid.3 \
man/sd_event_get_watchdog.3 \
man/sd_event_handler_t.3 \
man/sd_event_io_handler_t.3 \
man/sd_event_loop.3 \
man/sd_event_prepare.3 \
man/sd_event_ref.3 \
man/sd_event_signal_handler_t.3 \
man/sd_event_source.3 \
man/sd_event_source_get_child_pid.3 \
man/sd_event_source_get_description.3 \
man/sd_event_source_get_enabled.3 \
man/sd_event_source_get_io_events.3 \
man/sd_event_source_get_io_fd.3 \
man/sd_event_source_get_io_revents.3 \
man/sd_event_source_get_priority.3 \
man/sd_event_source_get_signal.3 \
man/sd_event_source_get_time.3 \
man/sd_event_source_get_time_accuracy.3 \
man/sd_event_source_get_time_clock.3 \
man/sd_event_source_get_userdata.3 \
man/sd_event_source_ref.3 \
man/sd_event_source_set_io_events.3 \
man/sd_event_source_set_io_fd.3 \
man/sd_event_source_set_time.3 \
man/sd_event_source_set_time_accuracy.3 \
man/sd_event_time_handler_t.3 \
man/sd_event_unref.3 \
man/sd_id128_equal.3 \
man/sd_id128_from_string.3 \
@ -489,6 +534,19 @@ man/SD_CRIT.3: man/sd-daemon.3
man/SD_DEBUG.3: man/sd-daemon.3
man/SD_EMERG.3: man/sd-daemon.3
man/SD_ERR.3: man/sd-daemon.3
man/SD_EVENT_ARMED.3: man/sd_event_wait.3
man/SD_EVENT_EXITING.3: man/sd_event_wait.3
man/SD_EVENT_FINISHED.3: man/sd_event_wait.3
man/SD_EVENT_INITIAL.3: man/sd_event_wait.3
man/SD_EVENT_OFF.3: man/sd_event_source_set_enabled.3
man/SD_EVENT_ON.3: man/sd_event_source_set_enabled.3
man/SD_EVENT_ONESHOT.3: man/sd_event_source_set_enabled.3
man/SD_EVENT_PENDING.3: man/sd_event_wait.3
man/SD_EVENT_PREPARING.3: man/sd_event_wait.3
man/SD_EVENT_PRIORITY_IDLE.3: man/sd_event_source_set_priority.3
man/SD_EVENT_PRIORITY_IMPORTANT.3: man/sd_event_source_set_priority.3
man/SD_EVENT_PRIORITY_NORMAL.3: man/sd_event_source_set_priority.3
man/SD_EVENT_RUNNING.3: man/sd_event_wait.3
man/SD_ID128_CONST_STR.3: man/sd-id128.3
man/SD_ID128_FORMAT_STR.3: man/sd-id128.3
man/SD_ID128_FORMAT_VAL.3: man/sd-id128.3
@ -585,21 +643,41 @@ man/sd_bus_path_encode_many.3: man/sd_bus_path_encode.3
man/sd_bus_ref.3: man/sd_bus_new.3
man/sd_bus_release_name.3: man/sd_bus_request_name.3
man/sd_bus_unref.3: man/sd_bus_new.3
man/sd_event.3: man/sd_event_new.3
man/sd_event_add_exit.3: man/sd_event_add_defer.3
man/sd_event_add_post.3: man/sd_event_add_defer.3
man/sd_event_child_handler_t.3: man/sd_event_add_child.3
man/sd_event_default.3: man/sd_event_new.3
man/sd_event_dispatch.3: man/sd_event_wait.3
man/sd_event_get_name.3: man/sd_event_set_name.3
man/sd_event_get_exit_code.3: man/sd_event_exit.3
man/sd_event_get_state.3: man/sd_event_wait.3
man/sd_event_get_tid.3: man/sd_event_new.3
man/sd_event_get_watchdog.3: man/sd_event_set_watchdog.3
man/sd_event_handler_t.3: man/sd_event_add_defer.3
man/sd_event_io_handler_t.3: man/sd_event_add_io.3
man/sd_event_loop.3: man/sd_event_run.3
man/sd_event_prepare.3: man/sd_event_wait.3
man/sd_event_ref.3: man/sd_event_new.3
man/sd_event_signal_handler_t.3: man/sd_event_add_signal.3
man/sd_event_source.3: man/sd_event_add_io.3
man/sd_event_source_get_child_pid.3: man/sd_event_add_child.3
man/sd_event_source_get_description.3: man/sd_event_source_set_description.3
man/sd_event_source_get_enabled.3: man/sd_event_source_set_enabled.3
man/sd_event_source_get_io_events.3: man/sd_event_add_io.3
man/sd_event_source_get_io_fd.3: man/sd_event_add_io.3
man/sd_event_source_get_io_revents.3: man/sd_event_add_io.3
man/sd_event_source_get_priority.3: man/sd_event_source_set_priority.3
man/sd_event_source_get_signal.3: man/sd_event_add_signal.3
man/sd_event_source_get_time.3: man/sd_event_add_time.3
man/sd_event_source_get_time_accuracy.3: man/sd_event_add_time.3
man/sd_event_source_get_time_clock.3: man/sd_event_add_time.3
man/sd_event_source_get_userdata.3: man/sd_event_source_set_userdata.3
man/sd_event_source_ref.3: man/sd_event_source_unref.3
man/sd_event_source_set_io_events.3: man/sd_event_add_io.3
man/sd_event_source_set_io_fd.3: man/sd_event_add_io.3
man/sd_event_source_set_time.3: man/sd_event_add_time.3
man/sd_event_source_set_time_accuracy.3: man/sd_event_add_time.3
man/sd_event_time_handler_t.3: man/sd_event_add_time.3
man/sd_event_unref.3: man/sd_event_new.3
man/sd_id128_equal.3: man/sd-id128.3
man/sd_id128_from_string.3: man/sd_id128_to_string.3
@ -857,6 +935,45 @@ man/SD_EMERG.html: man/sd-daemon.html
man/SD_ERR.html: man/sd-daemon.html
$(html-alias)
man/SD_EVENT_ARMED.html: man/sd_event_wait.html
$(html-alias)
man/SD_EVENT_EXITING.html: man/sd_event_wait.html
$(html-alias)
man/SD_EVENT_FINISHED.html: man/sd_event_wait.html
$(html-alias)
man/SD_EVENT_INITIAL.html: man/sd_event_wait.html
$(html-alias)
man/SD_EVENT_OFF.html: man/sd_event_source_set_enabled.html
$(html-alias)
man/SD_EVENT_ON.html: man/sd_event_source_set_enabled.html
$(html-alias)
man/SD_EVENT_ONESHOT.html: man/sd_event_source_set_enabled.html
$(html-alias)
man/SD_EVENT_PENDING.html: man/sd_event_wait.html
$(html-alias)
man/SD_EVENT_PREPARING.html: man/sd_event_wait.html
$(html-alias)
man/SD_EVENT_PRIORITY_IDLE.html: man/sd_event_source_set_priority.html
$(html-alias)
man/SD_EVENT_PRIORITY_IMPORTANT.html: man/sd_event_source_set_priority.html
$(html-alias)
man/SD_EVENT_PRIORITY_NORMAL.html: man/sd_event_source_set_priority.html
$(html-alias)
man/SD_EVENT_RUNNING.html: man/sd_event_wait.html
$(html-alias)
man/SD_ID128_CONST_STR.html: man/sd-id128.html
$(html-alias)
@ -1145,19 +1262,40 @@ man/sd_bus_release_name.html: man/sd_bus_request_name.html
man/sd_bus_unref.html: man/sd_bus_new.html
$(html-alias)
man/sd_event.html: man/sd_event_new.html
$(html-alias)
man/sd_event_add_exit.html: man/sd_event_add_defer.html
$(html-alias)
man/sd_event_add_post.html: man/sd_event_add_defer.html
$(html-alias)
man/sd_event_child_handler_t.html: man/sd_event_add_child.html
$(html-alias)
man/sd_event_default.html: man/sd_event_new.html
$(html-alias)
man/sd_event_dispatch.html: man/sd_event_wait.html
$(html-alias)
man/sd_event_get_name.html: man/sd_event_set_name.html
man/sd_event_get_exit_code.html: man/sd_event_exit.html
$(html-alias)
man/sd_event_get_state.html: man/sd_event_wait.html
$(html-alias)
man/sd_event_get_tid.html: man/sd_event_new.html
$(html-alias)
man/sd_event_get_watchdog.html: man/sd_event_set_watchdog.html
$(html-alias)
man/sd_event_handler_t.html: man/sd_event_add_defer.html
$(html-alias)
man/sd_event_io_handler_t.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_loop.html: man/sd_event_run.html
@ -1169,9 +1307,33 @@ man/sd_event_prepare.html: man/sd_event_wait.html
man/sd_event_ref.html: man/sd_event_new.html
$(html-alias)
man/sd_event_signal_handler_t.html: man/sd_event_add_signal.html
$(html-alias)
man/sd_event_source.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_source_get_child_pid.html: man/sd_event_add_child.html
$(html-alias)
man/sd_event_source_get_description.html: man/sd_event_source_set_description.html
$(html-alias)
man/sd_event_source_get_enabled.html: man/sd_event_source_set_enabled.html
$(html-alias)
man/sd_event_source_get_io_events.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_source_get_io_fd.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_source_get_io_revents.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_source_get_priority.html: man/sd_event_source_set_priority.html
$(html-alias)
man/sd_event_source_get_signal.html: man/sd_event_add_signal.html
$(html-alias)
@ -1184,12 +1346,27 @@ man/sd_event_source_get_time_accuracy.html: man/sd_event_add_time.html
man/sd_event_source_get_time_clock.html: man/sd_event_add_time.html
$(html-alias)
man/sd_event_source_get_userdata.html: man/sd_event_source_set_userdata.html
$(html-alias)
man/sd_event_source_ref.html: man/sd_event_source_unref.html
$(html-alias)
man/sd_event_source_set_io_events.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_source_set_io_fd.html: man/sd_event_add_io.html
$(html-alias)
man/sd_event_source_set_time.html: man/sd_event_add_time.html
$(html-alias)
man/sd_event_source_set_time_accuracy.html: man/sd_event_add_time.html
$(html-alias)
man/sd_event_time_handler_t.html: man/sd_event_add_time.html
$(html-alias)
man/sd_event_unref.html: man/sd_event_new.html
$(html-alias)
@ -2264,6 +2441,7 @@ EXTRA_DIST += \
man/runlevel.xml \
man/sd-bus-errors.xml \
man/sd-daemon.xml \
man/sd-event.xml \
man/sd-id128.xml \
man/sd-journal.xml \
man/sd-login.xml \
@ -2286,12 +2464,23 @@ EXTRA_DIST += \
man/sd_bus_request_name.xml \
man/sd_event_add_child.xml \
man/sd_event_add_defer.xml \
man/sd_event_add_io.xml \
man/sd_event_add_signal.xml \
man/sd_event_add_time.xml \
man/sd_event_exit.xml \
man/sd_event_get_fd.xml \
man/sd_event_new.xml \
man/sd_event_now.xml \
man/sd_event_run.xml \
man/sd_event_set_name.xml \
man/sd_event_set_watchdog.xml \
man/sd_event_source_get_event.xml \
man/sd_event_source_get_pending.xml \
man/sd_event_source_set_description.xml \
man/sd_event_source_set_enabled.xml \
man/sd_event_source_set_prepare.xml \
man/sd_event_source_set_priority.xml \
man/sd_event_source_set_userdata.xml \
man/sd_event_source_unref.xml \
man/sd_event_wait.xml \
man/sd_get_seats.xml \
man/sd_id128_get_machine.xml \

4
man/sd-daemon.xml
View File

@ -71,10 +71,10 @@
<refsect1>
<title>Description</title>
<para><filename>sd-daemon.h</filename> provide APIs for new-style
<para><filename>sd-daemon.h</filename> provides APIs for new-style
daemons, as implemented by the
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
init system.</para>
service manager.</para>
<para>See
<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

187
man/sd-event.xml Normal file
View File

@ -0,0 +1,187 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd-event" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd-event</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd-event</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd-event</refname>
<refpurpose>A generic event loop implementation</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
</funcsynopsis>
<cmdsynopsis>
<command>pkg-config --cflags --libs libsystemd</command>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>sd-event.h</filename> provides a generic event
loop implementation, based on Linux <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
</para>
<para>See
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for more information about the functions available.</para>
<para>The event loop design is targeted on running a separate
instance of the event loop in each thread; it has no concept of
distributing events from a single event loop instance onto
multiple worker threads. Dispatching events is strictly ordered
and subject to configurable priorities. In each event loop
iteration a single event source is dispatched. Each time an event
source is dispatched the kernel is polled for new events, before
the next event source is dispatched. The event loop is designed to
honour priorities and provide fairness within each priority. It is
not designed to provide optimal throughput, as this contradicts
these goals due the limitations of the underlying <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
primitives.</para>
<para>The event loop implementation provides the following features:</para>
<orderedlist>
<listitem><para>I/O event sources, based on <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>'s
file descriptor watching, including edge triggered events (<constant>EPOLLET</constant>). See <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>Timer event sources, based on <citerefentry
project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
supporting the <constant>CLOCK_MONOTONIC</constant>,
<constant>CLOCK_REALTIME</constant>,
<constant>CLOCK_BOOTIME</constant> clocks, as well as the
<constant>CLOCK_REALTIME_ALARM</constant> and
<constant>CLOCK_BOOTTIME_ALARM</constant> clocks that can resume
the system from suspend. When creating timer events a required
accuracy parameter may be specified which allows coalescing of
timer events to minimize power consumption. See <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>UNIX process signal events, based on
<citerefentry
project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
including full support for real-time signals, and queued parameters. See <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>Child process state change events, based on
<citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>. See <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>Static event sources, of three types: defer,
post and exit, for invoking calls in each event loop, after
other event sources or at event loop termination. See
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>Event sources may be assigned a 64bit priority
value, that controls the order in which event sources are
dispatched if multiple are pending simultanously. See
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>The event loop may automatically send watchdog
notification messages to the service manager. See
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
<listitem><para>The event loop may be integrated into foreign
event loops, such as the GLib one. See
<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for an example.</para></listitem>
</orderedlist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_get_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

132
man/sd_event_add_child.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_add_child">
<refentry id="sd_event_add_child" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_child</title>
@ -45,13 +45,23 @@
<refnamediv>
<refname>sd_event_add_child</refname>
<refname>sd_event_source_get_child_pid</refname>
<refname>sd_event_child_handler_t</refname>
<refpurpose>Add a child state change event source to an event loop</refpurpose>
<refpurpose>Add a child process state change event source to an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_add_child</function></funcdef>
@ -63,13 +73,6 @@
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_child_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>const siginfo_t *<parameter>si</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_child_pid</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
@ -83,42 +86,75 @@
<title>Description</title>
<para><function>sd_event_add_child()</function> adds a new child
state change event source to an event loop object. The event loop
is specified in <parameter>event</parameter>, the event source is
returned in the <parameter>source</parameter> parameter. The
<parameter>pid</parameter> parameter specifies the process to
watch. The <parameter>handler</parameter> must reference a
function to call when the process changes state. The handler
function will be passed the <parameter>userdata</parameter>
pointer, which may be chosen freely by the caller. The handler
also receives a pointer to a <structname>const
siginfo_t</structname> structure containing the information about
the event. The <parameter>options</parameter> parameter determines
which state changes will be watched for. It must contain an OR-ed
mask of <constant>WEXITED</constant> (watch for the child
process state change event source to an event loop. The event loop
object is specified in the <parameter>event</parameter> parameter,
the event source object is returned in the
<parameter>source</parameter> parameter. The
<parameter>pid</parameter> parameter specifies the PID of the
process to watch. The <parameter>handler</parameter> must
reference a function to call when the process changes state. The
handler function will be passed the
<parameter>userdata</parameter> pointer, which may be chosen
freely by the caller. The handler also receives a pointer to a
<structname>siginfo_t</structname> structure containing
information about the child process event. The
<parameter>options</parameter> parameter determines which state
changes will be watched for. It must contain an OR-ed mask of
<constant>WEXITED</constant> (watch for the child process
terminating), <constant>WSTOPPED</constant> (watch for the child
being stopped by a signal), and <constant>WCONTINUED</constant>
(watch for the child being resumed by a signal). See
<citerefentry><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
process being stopped by a signal), and
<constant>WCONTINUED</constant> (watch for the child process being
resumed by a signal). See <citerefentry
project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for further information.</para>
<para>Only a single handler may be installed for a specific
child. The handler is enabled
for a single event (<constant>SD_EVENT_ONESHOT</constant>),
but this may be
changed with
child process. The handler is enabled for a single event
(<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If the handler function returns a negative error code, it will be
disabled after the invocation, even if
<constant>SD_EVENT_ON</constant> mode is set.
disabled after the invocation, even if the
<constant>SD_EVENT_ON</constant> mode was requested before.
</para>
<para>To destroy an event source object use
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop
when all references to the event source are dropped. To make sure
an event source does not fire anymore, even when there's still a
reference to it kept, consider setting the event source to
<constant>SD_EVENT_OFF</constant> with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the the second parameter of
<function>sd_event_add_child()</function> is passed as NULL no
reference to the event source object is returned. In this case the
event source is considered "floating", and will be destroyed
implicitly when the event loop itself is destroyed.</para>
<para>Note that the <parameter>handler</parameter> function is
invoked at a time where the child process is not reaped yet (and
thus still is exposed as a zombie process by the kernel). However,
the child will be reaped automatically after the function
returns. Child processes for which no child process state change
event sources are installed will not be reaped by the event loop
implementation.</para>
<para>If both a child process state change event source and a
<constant>SIGCHLD</constant> signal event source is installed in
the same event loop, the configured event source priorities decide
which event source is dispatched first. If the signal handler is
processed first, it should leave the child processes for which
child process state change event sources are installed unreaped.</para>
<para><function>sd_event_source_get_child_pid()</function>
retrieves the configured <parameter>pid</parameter> of a child
state change event source created previously with
retrieves the configured PID of a child process state change event
source created previously with
<function>sd_event_add_child()</function>. It takes the event
source object as the <parameter>source</parameter> parameter and a
pointer to <type>pid_t</type> to return the result in.
pointer to a <type>pid_t</type> variable to return the process ID
in.
</para>
</refsect1>
@ -158,7 +194,7 @@
<term><constant>-EBUSY</constant></term>
<listitem><para>A handler is already installed for this
child.</para></listitem>
child process.</para></listitem>
</varlistentry>
@ -176,18 +212,16 @@
</varlistentry>
<varlistentry>
<term><constant>-EDOM</constant></term>
<listitem><para>The passed event source is not a child process event source.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_event_add_child()</function> and the other functions
described here are available as a shared library, which can be
compiled and linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -196,10 +230,16 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>

101
man/sd_event_add_defer.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_add_defer">
<refentry id="sd_event_add_defer" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_defer</title>
@ -46,13 +46,22 @@
<refname>sd_event_add_defer</refname>
<refname>sd_event_add_post</refname>
<refname>sd_event_add_exit</refname>
<refname>sd_event_handler_t</refname>
<refpurpose>Add static event sources to an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_add_defer</function></funcdef>
@ -78,49 +87,67 @@
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>These three functions add new event sources to an event loop
object. The event loop is specified in
<parameter>event</parameter>, the event source is returned in the
<parameter>source</parameter> parameter. The event sources are
enabled statically and will "fire" when the event loop is run and
the conditions described below are met. The handler function will
be passed the <parameter>userdata</parameter> pointer, which may
be chosen freely by the caller.</para>
<para>These three functions add new static event sources to an
event loop. The event loop object is specified in the
<parameter>event</parameter> parameter, the event source object is
returned in the <parameter>source</parameter> parameter. The event
sources are enabled statically and will "fire" when the event loop
is run and the conditions described below are met. The handler
function will be passed the <parameter>userdata</parameter>
pointer, which may be chosen freely by the caller.</para>
<para><function>sd_event_add_defer()</function> adds a new event
source that will "fire" the next time the event loop is run. By
default, the handler will be called once
(<constant>SD_EVENT_ONESHOT</constant>).</para>
source that will be dispatched instantly, before the event loop
goes to sleep again and waits for new events. By default, the
handler will be called once
(<constant>SD_EVENT_ONESHOT</constant>). Note that if the event
source is set to <constant>SD_EVENT_ON</constant> the event loop
will never go to sleep again, but continously call the handler,
possibly interleaved with other event sources.</para>
<para><function>sd_event_add_post()</function> adds a new event
source that will "fire" if any event handlers are invoked whenever
the event loop is run. By default, the source is enabled
permanently (<constant>SD_EVENT_ON</constant>).</para>
source that is run before the event loop will sleep and wait
for new events, but only after at least one other non-post event
source was dispatched. By default, the source is enabled
permanently (<constant>SD_EVENT_ON</constant>). Note that this
event source type will still allow the event loop to go to sleep
again, even if set to <constant>SD_EVENT_ON</constant>, as long as
no other event source is ever triggered.</para>
<para><function>sd_event_add_exit()</function> adds a new event
source that will "fire" when the event loop is terminated
with <function>sd_event_exit()</function>.</para>
source that will be dispatched when the event loop is terminated
with <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>The
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
function may be used to enable the event source permanently
(<constant>SD_EVENT_ON</constant>) or to make it fire just once
(<constant>SD_EVENT_ONESHOT</constant>). If the handler function
returns a negative error code, it will be disabled after the
invocation, even if <constant>SD_EVENT_ON</constant> mode is
set.</para>
(<constant>SD_EVENT_ONESHOT</constant>).</para>
<para>If the handler function returns a negative error code, it
will be disabled after the invocation, even if the
<constant>SD_EVENT_ON</constant> mode was requested before.</para>
<para>To destroy an event source object use
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop
when all references to the event source are dropped. To make sure
an event source does not fire anymore, even when there's still a
reference to it kept, consider setting the event source to
<constant>SD_EVENT_OFF</constant> with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the second parameter of these functions is passed as
NULL no reference to the event source object is returned. In this
case the event source is considered "floating", and will be
destroyed implicitly when the event loop itself is
destroyed.</para>
</refsect1>
<refsect1>
@ -164,15 +191,7 @@
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>Functions described here are available as a shared library,
which can be compiled and linked to with the
<constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -181,10 +200,16 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

300
man/sd_event_add_io.xml Normal file
View File

@ -0,0 +1,300 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_add_io" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_io</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_add_io</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_add_io</refname>
<refname>sd_event_source_get_io_events</refname>
<refname>sd_event_source_set_io_events</refname>
<refname>sd_event_source_get_io_revents</refname>
<refname>sd_event_source_get_io_fd</refname>
<refname>sd_event_source_set_io_fd</refname>
<refname>sd_event_source</refname>
<refname>sd_event_io_handler_t</refname>
<refpurpose>Add an I/O event source to an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_io_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>uint32_t <parameter>revents</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_add_io</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>sd_event_source **<parameter>source</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>uint32_t <parameter>events</parameter></paramdef>
<paramdef>sd_event_io_handler_t <parameter>handler</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_io_events</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>uint32_t *<parameter>events</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_set_io_events</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>uint32_t <parameter>events</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_io_revents</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>uint32_t *<parameter>revents</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_io_fd</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_set_io_fd</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_add_io()</function> adds a new I/O event
source to an event loop. The event loop object is specified in the
<parameter>event</parameter> parameter, the event source object is
returned in the <parameter>source</parameter> parameter. The
<parameter>fd</parameter> parameter takes the UNIX file descriptor
to watch, which may refer to a socket, a FIFO, a message queue, a
serial connection, a character device or any other file descriptor
compatible with Linux <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
<parameter>events</parameter> parameter takes a bit mask of I/O
events to watch the file descriptor for, a combination of the
following event flags: <constant>EPOLLIN</constant>,
<constant>EPOLLOUT</constant>, <constant>EPOLLRDHUP</constant>,
<constant>EPOLLPRI</constant> and <constant>EPOLLET</constant>,
see <citerefentry
project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details. The <parameter>handler</parameter> shall reference a
function to call when the I/O event source is triggered. The
handler function will be passed the
<parameter>userdata</parameter> pointer, which may be chosen
freely by the caller. The handler will also be passed the file
descriptor the event was seen on as well as the actual event flags
seen. It's generally a subset of the events watched, however may
additionally have <constant>EPOLLERR</constant> and
<constant>EPOLLHUP</constant> set.</para>
<para>By default, the I/O event source will stay enabled
continously (<constant>SD_EVENT_ON</constant>), but this may be
changed with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If the handler function returns a negative error code, it will be
disabled after the invocation, even if the
<constant>SD_EVENT_ON</constant> mode was requested before. Note
that an I/O event source set to <constant>SD_EVENT_ON</constant> will
fire continously unless data is read or written to the file
descriptor in order to reset the mask of events seen.
</para>
<para>Setting the I/O event mask to watch for to 0 does not mean
that the event source won't be triggered anymore, as
<constant>EPOLLHUP</constant> and <constant>EPOLLERR</constant>
may be triggered even with a zero event mask. To temporarily
disable an I/O event source use
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
with <constant>SD_EVENT_OFF</constant> instead.</para>
<para>To destroy an event source object use
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop
when all references to the event source are dropped. To make sure
an event source does not fire anymore, even when there's still a
reference to it kept, consider setting the event source to
<constant>SD_EVENT_OFF</constant> with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the the second parameter of
<function>sd_event_add_io()</function> is passed as NULL no
reference to the event source object is returned. In this case the
event source is considered "floating", and will be destroyed
implicitly when the event loop itself is destroyed.</para>
<para>It is recommended to use
<function>sd_event_add_io()</function> only in conjunction with
file descriptors that have <constant>O_NONBLOCK</constant> set, to
ensure that all I/O operations from invoked handlers are properly
asynchronous and non-blocking. Using file descriptors without
<constant>O_NONBLOCK</constant> might result in unexpected
starving of other event sources. See <citerefentry
project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
<para><function>sd_event_source_get_io_events()</function> retrieves
the configured I/O event mask to watch of an I/O event source created
previously with <function>sd_event_add_io()</function>. It takes
the event source object and a pointer to a variable to store the
event mask in.</para>
<para><function>sd_event_source_set_io_events()</function> changes the
configured I/O event mask to watch of an I/O event source created previously
with <function>sd_event_add_io()</function>. It takes the event
source object and the new event mask to set.</para>
<para><function>sd_event_source_get_io_events()</function>
retrieves the I/O event mask of currently seen but undispatched
events from an I/O event source created previously with
<function>sd_event_add_io()</function>. It takes the event source
object and a pointer to a variable to store the event mask
in. When called from a handler function on the handler's event
source object this will return the same mask as passed to the
handler's <parameter>revents</parameter> parameter. This call is
primarily useful to check for undispatched events of an event
source from the handler of an unrelated (possibly higher priority)
event source. Note the relation between
<function>sd_event_source_get_pending()</function> and
<function>sd_event_source_get_io_revents()</function>: both
functions will report non-zero results when there's an event
pending for the event source, but the former applies to all event
source types, the latter only to I/O event sources.</para>
<para><function>sd_event_source_get_io_fd()</function> retrieves
the UNIX file descriptor of an I/O event source created previously
with <function>sd_event_add_io()</function>. It takes the event
source object and returns the positive file descriptor in the return
value, or a negative error number on error (see below).</para>
<para><function>sd_event_source_set_io_fd()</function>
changes the UNIX file descriptor of an I/O event source created
previously with <function>sd_event_add_io()</function>. It takes
the event source object and the new file descriptor to set.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive
integer. On failure, they return a negative errno-style error
code. </para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory to allocate an object.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>An invalid argument has been passed.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESTALE</constant></term>
<listitem><para>The event loop is already terminated.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EDOM</constant></term>
<listitem><para>The passed event source is not an I/O event source.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_get_pending</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

118
man/sd_event_add_signal.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_add_signal">
<refentry id="sd_event_add_signal" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_signal</title>
@ -45,13 +45,24 @@
<refnamediv>
<refname>sd_event_add_signal</refname>
<refname>sd_event_source_get_signal</refname>
<refname>sd_event_signal_handler_t</refname>
<refpurpose>Add a signal event source to an event loop</refpurpose>
<refpurpose>Add a UNIX process signal event source to an event
loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_add_signal</function></funcdef>
@ -62,13 +73,6 @@
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_signal_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>const struct signalfd_siginfo *<parameter>si</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_signal</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
@ -80,41 +84,61 @@
<refsect1>
<title>Description</title>
<para><function>sd_event_add_signal()</function> adds a new signal
event source to an event loop object. The event loop is specified
in <parameter>event</parameter>, and the event source is returned in
the <parameter>source</parameter> parameter. The
<parameter>signal</parameter> parameter specifies the signal to be handled
(see
<citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
The <parameter>handler</parameter> must reference a function to
call when the signal is delivered or be <constant>NULL</constant>.
The handler function will be passed the
<parameter>userdata</parameter> pointer, which may be chosen
<para><function>sd_event_add_signal()</function> adds a new UNIX
process signal event source to an event loop. The event loop
object is specified in the <parameter>event</parameter> parameter,
and the event source object is returned in the
<parameter>source</parameter> parameter. The
<parameter>signal</parameter> parameter specifies the numeric
signal to be handled (see <citerefentry
project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
The <parameter>handler</parameter> parameter must reference a
function to call when the signal is received or be
<constant>NULL</constant>. The handler function will be passed
the <parameter>userdata</parameter> pointer, which may be chosen
freely by the caller. The handler also receives a pointer to a
<structname>const struct signalfd_siginfo</structname> containing
the information about the received signal. See
<citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
<structname>signalfd_siginfo</structname> structure containing
information about the received signal. See <citerefentry
project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for further information.</para>
<para>Only a single handler may be installed for a specific
signal. The signal will be unblocked, and must be
blocked when the function is called. If the handler is not
specified (<parameter>handler</parameter> is
signal. The signal will be unblocked by this call, and must be
blocked before this function is called in all threads (using
<citerefentry
project='man-pages'><refentrytitle>sigprocmask</refentrytitle><manvolnum>2</manvolnum></citerefentry>). If
the handler is not specified (<parameter>handler</parameter> is
<constant>NULL</constant>), a default handler which causes the
program to exit will be used. By default, the handler is enabled
permanently (<constant>SD_EVENT_ON</constant>), but this may be
changed with
program to exit cleanly will be used.</para>
<para>By default, the event source is enabled permanently
(<constant>SD_EVENT_ON</constant>), but this may be changed with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If the handler function returns a negative error code, it will be
disabled after the invocation, even if
<constant>SD_EVENT_ON</constant> mode is set.
disabled after the invocation, even if the
<constant>SD_EVENT_ON</constant> mode was requested before.
</para>
<para>To destroy an event source object use
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop
when all references to the event source are dropped. To make sure
an event source does not fire anymore, even when there's still a
reference to it kept, consider setting the event source to
<constant>SD_EVENT_OFF</constant> with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the the second parameter of
<function>sd_event_add_signal()</function> is passed as NULL no
reference to the event source object is returned. In this case the
event source is considered "floating", and will be destroyed
implicitly when the event loop itself is destroyed.</para>
<para><function>sd_event_source_get_signal()</function> retrieves
the configured signal number of a signal event source created
previously with <function>sd_event_add_signal()</function>. It
takes the event source object as the <parameter>source</parameter>
the configured UNIX process signal number of a signal event source
created previously with
<function>sd_event_add_signal()</function>. It takes the event
source object as the <parameter>source</parameter>
parameter.</para>
</refsect1>
@ -168,18 +192,16 @@
</varlistentry>
<varlistentry>
<term><constant>-EDOM</constant></term>
<listitem><para>The passed event source is not a signal event source.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_event_add_signal()</function> and the other functions
described here are available as a shared library, which can be
compiled and linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -188,10 +210,16 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>signalfd</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>

167
man/sd_event_add_time.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_add_time">
<refentry id="sd_event_add_time" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_time</title>
@ -49,13 +49,23 @@
<refname>sd_event_source_get_time_accuracy</refname>
<refname>sd_event_source_set_time_accuracy</refname>
<refname>sd_event_source_get_time_clock</refname>
<refname>sd_event_time_handler_t</refname>
<refpurpose>Add a timer event source to an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>uint64_t <parameter>usec</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_add_time</function></funcdef>
@ -68,35 +78,28 @@
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_time_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>uint64_t <parameter>usec</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_time</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>usec_t *<parameter>usec</parameter></paramdef>
<paramdef>uint64_t *<parameter>usec</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_set_time</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>usec_t <parameter>usec</parameter></paramdef>
<paramdef>uint64_t <parameter>usec</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_time_accuracy</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>usec_t *<parameter>usec</parameter></paramdef>
<paramdef>uint64_t *<parameter>usec</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_set_time_accuracy</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>usec_t <parameter>usec</parameter></paramdef>
<paramdef>uint64_t <parameter>usec</parameter></paramdef>
</funcprototype>
<funcprototype>
@ -112,73 +115,130 @@
<title>Description</title>
<para><function>sd_event_add_time()</function> adds a new timer
event source to an event loop object. The event loop is specified
in <parameter>event</parameter>, the event source is returned in
the <parameter>source</parameter> parameter. The
<parameter>clock</parameter> parameter takes a clock identifier,
one of <constant>CLOCK_REALTIME</constant>,
<constant>CLOCK_MONOTONIC</constant> and
event source to an event loop. The event loop object is specified
in the <parameter>event</parameter> parameter, the event source
object is returned in the <parameter>source</parameter>
parameter. The <parameter>clock</parameter> parameter takes a
clock identifier, one of <constant>CLOCK_REALTIME</constant>,
<constant>CLOCK_MONOTONIC</constant>,
<constant>CLOCK_BOOTTIME</constant>,
<constant>CLOCK_REALTIME_ALARM</constant> or
<constant>CLOCK_BOOTTIME_ALARM</constant>. See
<citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details regarding the various types of clocks. The
<parameter>usec</parameter> parameter takes a time value in
microseconds, relative to the clock's epoch specifying when the
timer shall elapse the earliest. The
microseconds (µs), relative to the clock's epoch, specifying when
the timer shall elapse the earliest. If a time that already lies
in the past is specified (including 0), the timer source is
dispatched immediately in the next event loop iterations. The
<parameter>accuracy</parameter> parameter takes an additional
accuracy value in microseconds specifying a time the timer event
may be delayed. Specify 0 for selecting the default accuracy
(250ms). Specify 1 for most accurate timers. Consider specifying
60000000 or larger (1h) for long-running events that may be
accuracy value in µs specifying a time the timer event may be
delayed. Specify 0 for selecting the default accuracy
(250ms). Specify 1µs for most accurate timers. Consider specifying
60000000µs or larger (1min) for long-running events that may be
delayed substantially. Picking higher accuracy values allows the
system to coalesce timer events more aggressively, thus improving
power efficiency. The <parameter>handler</parameter> shall
reference a function to call when the timer elapses. The handler
function will be passed the <parameter>userdata</parameter>
pointer, which may be chosen freely by the caller. The handler is
also passed the configured time it was triggered, however it might
actually have been called at a slightly later time, subject to the
specified accuracy value, the kernel timer slack (see
power efficiency. The <parameter>handler</parameter> parameter
shall reference a function to call when the timer elapses. The
handler function will be passed the
<parameter>userdata</parameter> pointer, which may be chosen
freely by the caller. The handler is also passed the configured
time it was triggered, however it might actually have been called
at a slightly later time, subject to the specified accuracy value,
the kernel timer slack (see
<citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
and additional scheduling latencies.</para>
and additional scheduling latencies. To query the actual time the
handler was called use
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>By default, the timer will elapse once
(<constant>SD_EVENT_ONESHOT</constant>), but this may be changed
with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If the handler function returns a negative error code, it will be
disabled after the invocation, even if
<constant>SD_EVENT_ON</constant> mode is set.
disabled after the invocation, even if the
<constant>SD_EVENT_ON</constant> mode was requested before. Note
that a timer event set to <constant>SD_EVENT_ON</constant> will
fire continously unless its configured time is updated using
<function>sd_event_source_set_time()</function>.
</para>
<para>To destroy an event source object use
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop
when all references to the event source are dropped. To make sure
an event source does not fire anymore, even when there's still a
reference to it kept, consider setting the event source to
<constant>SD_EVENT_OFF</constant> with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the the second parameter of
<function>sd_event_add_time()</function> is passed as NULL no
reference to the event source object is returned. In this case the
event source is considered "floating", and will be destroyed
implicitly when the event loop itself is destroyed.</para>
<para>If the <parameter>handler</parameter> to
<function>sd_event_add_time()</function> is passed as NULL, and
the event source fires, this will be considered a request to exit
the event loop. In this case, the <parameter>userdata</parameter>
parameter, cast to an integer is used for the exit code passed to
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
<constant>CLOCK_REALTIME_ALARM</constant> to define event sources
that may wake up the system from suspend.</para>
<para>In order to set up relative timers (that is, relative to the
current time), retrieve the current time via
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
add the desired timespan to sleep to it, and pass the result as
the <parameter>usec</parameter> parameter to
<function>sd_event_add_time()</function>.</para>
<para>In order to set up repetitive timers (that is, timers that
are triggered in regular intervals), set up the timer normally,
for the first invocation. Each time the event handler is invoked,
update the timer's trigger time with
<citerefentry><refentrytitle>sd_event_source_set_time</refentrytitle><manvolnum>3</manvolnum></citerefentry> for the next timer
iteration, and reenable the timer using
<function>sd_event_source_set_enabled()</function>. To calculate
the next point in time to pass to
<function>sd_event_source_set_time()</function>, either use as
base the <parameter>usec</parameter> parameter passed to the timer
callback, or the timestamp returned by
<function>sd_event_now()</function>. In the former case timer
events will be regular, while in the latter case the scheduling
latency will keep accumulating on the timer.</para>
<para><function>sd_event_source_get_time()</function> retrieves
the configured time value of a timer event source created
previously with <function>sd_event_add_time()</function>. It takes
the event source object and a pointer to a variable to store the
time in microseconds in.</para>
time, relative to the selected clock's epoch, in µs in.</para>
<para><function>sd_event_source_set_time()</function> changes the
configured time value of a timer event source created previously
with <function>sd_event_add_time()</function>. It takes the event
source object and a time relative to the selected clock's
epoch, in microseconds.</para>
epoch, in µs.</para>
<para><function>sd_event_source_get_time_accuracy()</function>
retrieves the configured accuracy value of a timer event source
created previously with <function>sd_event_add_time()</function>. It
takes the event source object and a pointer to a variable to store
the accuracy in microseconds in.</para>
the accuracy in µs in.</para>
<para><function>sd_event_source_set_time_accuracy()</function>
changes the configured accuracy of a timer event source created
previously with <function>sd_event_add_time()</function>. It takes
the event source object and an accuracy, in microseconds.</para>
the event source object and an accuracy, in µs.</para>
<para><function>sd_event_source_get_time_clock()</function>
retrieves the configured clock of a timer event source created
previously with <function>sd_event_add_time()</function>. It takes
the event source object and a pointer to a variable to store the
clock identifier in.</para>
</refsect1>
<refsect1>
@ -228,18 +288,16 @@
<listitem><para>The selected clock is not supported by the event loop implementation.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EDOM</constant></term>
<listitem><para>The passed event source is not a timer event source.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_event_add_time()</function> and the other functions
described here are available as a shared library, which can be
compiled and linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -248,11 +306,18 @@
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>

163
man/sd_event_exit.xml Normal file
View File

@ -0,0 +1,163 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_exit" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_exit</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_exit</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_exit</refname>
<refname>sd_event_get_exit_code</refname>
<refpurpose>Ask the event loop to exit</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_exit</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>int <parameter>code</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_get_exit_code</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>int *<parameter>code</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_exit()</function> requests the event loop
specified in the <parameter>event</parameter> event loop object to
exit. The <parameter>code</parameter> parameter may be any integer
value and is returned as-is by
<citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
after the last event loop iteration. It may also be be queried
using <function>sd_event_get_exit_code()</function>, see
below. </para>
<para>When exiting is requested the event loop will stop listening
for and dispatching regular event sources. Instead it will proceed
with executing only event sources registered with
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
in the order defined by their priority. After all exit event
sources have been dispatched the event loop is terminated.</para>
<para>If <function>sd_event_exit()</function> is invoked a second
time while the event loop is still processing exit event sources,
the exit code stored in the event loop object is updated, but
otherwise no further operation is executed.</para>
<para><function>sd_event_get_exit_code()</function> may be used to
query the exit code passed into
<function>sd_event_exit()</function> earlier.</para>
<para>While the full positive and negative integer ranges may be used
for the exit code, care should be taken not pick exit codes that
conflict with regular exit codes returned by
<function>sd_event_loop()</function>, if these exit codes shall be
distinguishable.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_exit()</function> and
<function>sd_event_get_exit_code()</function> return 0 or a positive
integer. On failure, they return a negative errno-style error
code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>The event loop object or error code pointer are invalid.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop was created in a different process.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESTALE</constant></term>
<listitem><para>The event loop has exited already and all exit handlers are already processed.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENODATA</constant></term>
<listitem><para>The event loop has not been requested to exit yet.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

43
man/sd_event_get_fd.xml
View File

@ -21,8 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_get_fd"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentry id="sd_event_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_get_fd</title>
@ -51,11 +50,11 @@
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_get_fd</function></funcdef>
<paramdef>sd_bus *<parameter>event</parameter></paramdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@ -65,19 +64,29 @@
<title>Description</title>
<para><function>sd_event_get_fd()</function> returns the file
descriptor that the event loop object returned by the
descriptor that an event loop object returned by the
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>
function uses to wait for events. This file descriptor can be
polled for events. This makes it possible to embed the
function uses to wait for events. This file descriptor may itself
be polled for
<constant>POLLIN</constant>/<constant>EPOLLIN</constant>
events. This makes it possible to embed an
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
event loop inside of another event loop.</para>
event loop into another, possibly foreign, event loop.</para>
<para>The returned file descriptor refers to an <citerefentry
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
object. It is recommended not to alter it by invoking
<citerefentry
project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
on it, in order to avoid interference with the event loop's inner
logic and assumptions.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_get_fd()</function> returns a
non-negative integer. On failure, it returns a negative
non-negative file descriptor. On failure, it returns a negative
errno-style error code.</para>
</refsect1>
@ -108,21 +117,13 @@
<title>Examples</title>
<example>
<title>Integration in glib event loop</title>
<title>Integration in the GLib event loop</title>
<programlisting><xi:include href="glib-event-glue.c" parse="text" /></programlisting>
</example>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_event_get_fd()</function> is available as a
shared library, which can be compiled and linked to with the
<constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -130,7 +131,9 @@
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>
</refsect1>

73
man/sd_event_new.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_new">
<refentry id="sd_event_new" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_new</title>
@ -47,32 +47,42 @@
<refname>sd_event_default</refname>
<refname>sd_event_ref</refname>
<refname>sd_event_unref</refname>
<refname>sd_event_get_tid</refname>
<refname>sd_event</refname>
<refpurpose>Acquire and release an event loop object</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event sd_event;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_new</function></funcdef>
<paramdef>sd_bus **<parameter>event</parameter></paramdef>
<paramdef>sd_event **<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_default</function></funcdef>
<paramdef>sd_bus **<parameter>event</parameter></paramdef>
<paramdef>sd_event **<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_bus *<function>sd_event_ref</function></funcdef>
<paramdef>sd_bus *<parameter>event</parameter></paramdef>
<funcdef>sd_event *<function>sd_event_ref</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_bus *<function>sd_event_unref</function></funcdef>
<paramdef>sd_bus *<parameter>event</parameter></paramdef>
<funcdef>sd_event *<function>sd_event_unref</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_get_tid</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>pid_t *<parameter>tid</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@ -103,6 +113,17 @@
thread. All threads have exactly either zero or one default event loop
objects associated, but never more.</para>
<para>After allocating an event loop object, add event sources to
it with
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
and then execute the event loop using
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para><function>sd_event_ref()</function> increases the reference
count of the specified event loop object by one.</para>
@ -117,6 +138,19 @@
distinct objects. Note that, in order to free an event loop object,
all remaining event sources of the event loop also need to be
freed as each keeps a reference to it.</para>
<para>Both <function>sd_event_ref()</function> and
<function>sd_event_unref()</function> execute no operation if the
passed in event loop object is <constant>NULL</constant>.</para>
<para><function>sd_event_get_tid()</function> retrieves the thread
identifier ("TID") of the thread the specified event loop object
is associated with. This call is only supported for event loops
allocated with <function>sd_event_default()</function>, and
returns the identifier for the thread the event loop is the
default event loop of. See <citerefentry
project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for more information on thread identifiers.</para>
</refsect1>
<refsect1>
@ -149,18 +183,19 @@
<listitem><para>The maximum number of event loops has been allocated.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENXIO</constant></term>
<listitem><para><function>sd_event_get_tid()</function> was
invoked on an event loop object that was not allocated with
<function>sd_event_default()</function>.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_event_new()</function> and the other functions
described here are available as a shared library, which can be
compiled and linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -174,7 +209,9 @@
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>gettid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>

141
man/sd_event_now.xml Normal file
View File

@ -0,0 +1,141 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_now" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_now</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_now</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_now</refname>
<refpurpose>Retrieve current event loop iteration timestamp</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_now</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>clockid_t <parameter>clock</parameter></paramdef>
<paramdef>uint64_t *<parameter>usec</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_now()</function> returns the timestamp
the most recent event loop iteration began. This timestamp is
taken right after after returning from the event sleep, and before
dispatching any event sources. The <parameter>event</parameter>
parameter takes the even loop object to retrieve the timestamp
from. The <parameter>clock</parameter> parameter specifies the clock to
retrieve the timestamp for, and is one of
<constant>CLOCK_REALTIME</constant> (or its equivalent
<constant>CLOCK_REALTIME_ALARM</constant>),
<constant>CLOCK_MONOTONIC</constant> or
<constant>CLOCK_BOOTTIME</constant> (or its equivalent
<constant>CLOCK_BOOTTIME_ALARM</constant>), see <citerefentry
project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for more information on the various clocks. The retrieved
timestamp is stored in the <parameter>usec</parameter> parameter,
in µs since the clock's epoch. If this function is invoked before
the first event loop iteration the current time is returned, as
reported by <function>clock_gettime()</function>. To distinguish
this case from a regular invocation the return value will be
positive non-zero in this case, while it is zero when the returned
timestamp refers to the actual event loop iteration.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>If the first event loop iteration has not run yet
<function>sd_event_now()</function> returns the requested
timestamp in <parameter>usec</parameter> and returns a positive,
non-zero return value. Otherwise, on success it will return the
iteration's timestamp in <parameter>usec</parameter> and 0 as
return value. On failure, the call returns a negative errno-style
error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>An invalid parameter was
passed.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop object was created in a
different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

93
man/sd_event_run.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_run">
<refentry id="sd_event_run" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_run</title>
@ -46,7 +46,7 @@
<refname>sd_event_run</refname>
<refname>sd_event_loop</refname>
<refpurpose>Run the libsystemd event loop</refpurpose>
<refpurpose>Run an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -56,7 +56,7 @@
<funcprototype>
<funcdef>int <function>sd_event_run</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>uint64_t <parameter>timeout</parameter></paramdef>
<paramdef>uint64_t <parameter>usec</parameter></paramdef>
</funcprototype>
<funcprototype>
@ -69,47 +69,60 @@
<refsect1>
<title>Description</title>
<para><function>sd_event_run()</function> can be used to run one
iteration of the event loop of libsystemd. This function waits
until an event to process is available, and dispatches a handler
for it. The <parameter>timeout</parameter> parameter specifices the
maximum time (in microseconds) to wait. <constant>(uint64_t)
-1</constant> may be used to specify an infinite timeout.</para>
<para><function>sd_event_run()</function> may be used to run a single
iteration of the event loop specified in the
<parameter>event</parameter> parameter. The function waits until an event to
process is available, and dispatches the registered handler for
it. The <parameter>usec</parameter> parameter specifies the
maximum time (in microseconds) to wait for an event. Use
<constant>(uint64_t) -1</constant> to specify an infinite
timeout.</para>
<para><function>sd_event_loop</function> runs
<function>sd_event_wait</function> in a loop with a timeout of
infinity. This makes it suitable for the main event loop of a
program.</para>
<para><function>sd_event_loop()</function> invokes
<function>sd_event_run()</function> in a loop, thus implementing
the actual event loop. The call returns as soon as exiting was
requested using
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>The event loop object <parameter>event</parameter> is
created with
<function>sd_event_new</function>.
Events to wait for and their handlers can be registered with
<function>sd_event_add_time</function>,
<function>sd_event_add_child</function>,
<function>sd_event_add_signal</function>,
<function>sd_event_add_defer</function>,
<function>sd_event_add_exit</function>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
Events sources to wait for and their handlers may be registered
with
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
<function>sd_event_add_post</function>.
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
<para>For more fine-grained control,
<function>sd_event_prepare</function>,
<function>sd_event_wait</function>, and
<function>sd_event_dispatch</function> may be used. Along with
<function>sd_event_get_fd</function>, those functions make it
possible to integrate the libsystemd loop inside of another event
loop.</para>
<para>For low-level control of event loop execution, use
<citerefentry><refentrytitle>sd_event_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>sd_event_dispatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
which are wrapped by <function>sd_event_run()</function>. Along
with
<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
these functions allow integration of an
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
event loop into foreign event loop implementations.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer.
On failure, they return a negative errno-style error code.
<function>sd_event_run</function> returns 0 if the event loop is
finished, and a positive value if it can be continued.</para>
<para>On failure, these functions return a negative errno-style
error code. <function>sd_event_run()</function> returns a
positive, non-zero integer if an event source was dispatched, and
zero when the specified timeout hit before an event source has
seen any event, and hence no event source was
dispatched. <function>sd_event_loop()</function> returns the exit
code specified when invoking
<function>sd_event_exit()</function>.</para>
</refsect1>
<refsect1>
@ -122,7 +135,7 @@
<term><constant>-EINVAL</constant></term>
<listitem><para>The <parameter>event</parameter> parameter is
<constant>NULL</constant>.</para></listitem>
invalid or <constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
@ -153,15 +166,7 @@
<para>Other errors are possible, too.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para><function>sd_event_run()</function> and
<function>sd_event_loop()</function> are available
as a shared library, which can be compiled and linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -169,13 +174,15 @@
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<ulink url="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html">GLib Main Event Loop</ulink>.
</para>
</refsect1>

151
man/sd_event_set_name.xml
View File

@ -1,151 +0,0 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2014 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_set_name"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_set_name</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>More text</contrib>
<firstname>Zbigniew</firstname>
<surname>Jędrzejewski-Szmek</surname>
<email>zbyszek@in.waw.pl</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_set_name</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_set_name</refname>
<refname>sd_event_get_name</refname>
<refpurpose>Set human-readable names for event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_set_name</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>const char *<parameter>name</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_get_name</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>const char **<parameter>name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_set_name()</function> can be used to set
an arbitrary name for the event source
<parameter>source</parameter>. This name will be used in error
messages generated by
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for this source. The <parameter>name</parameter> must point
to a <constant>NUL</constant>-terminated string or be
<constant>NULL</constant>. In the latter case, the name will be
unset. The string is copied internally, so the
<parameter>name</parameter> argument is not referenced after the
function returns.</para>
<para><function>sd_event_set_name()</function> can be used to
query the current name assigned to source
<parameter>source</parameter>. It returns a pointer to the current
name (possibly <constant>NULL</constant>) in
<parameter>name</parameter>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_set_name()</function> and
<function>sd_event_get_name()</function> return a
non-negative integer. On failure, they return a negative
errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>source</parameter> is not a valid
pointer to an <structname>sd_event_source</structname>
structure or the <parameter>name</parameter> argument for
<function>sd_event_get_name()</function> is
<constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory to copy the
name.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The functions described here are available as a
shared library, which can be compiled and linked to with the
<constant>libsystemd</constant> <citerefentry
project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

177
man/sd_event_set_watchdog.xml Normal file
View File

@ -0,0 +1,177 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_set_watchdog" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_set_watchdog</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_set_watchdog</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_set_watchdog</refname>
<refname>sd_event_get_watchdog</refname>
<refpurpose>Enable event loop watchdog support</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_set_watchdog</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>int b</paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_get_watchdog</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_set_watchdog()</function> may be used to
enable or disable automatic watchdog notification support in the
event loop object specified in the <parameter>event</parameter>
parameter. Specifically, depending on the <parameter>b</parameter>
boolean argument this will make sure the event loop wakes up in
regular intervals and sends watchdog notification messages to the
service manager, if this was requested by the service
manager. Watchdog support is determined with
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
and watchdog messages are sent with
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. See
the <varname>WatchdogSec=</varname> setting in
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details on how to enable watchdog support for a service and
the protocol used. The wake-up interval is chosen as half the
watchdog timeout declared by the service manager via the
<varname>$WATCHDOG_USEC</varname> environment variable. If the
service manager did not request watchdog notifications, or if the
process was not invoked by the service manager this call with a
true <parameter>b</parameter> parameter executes no
operation. Passing a false <parameter>b</parameter> parameter will
disable the automatic sending of watchdog notification messages if
it was enabled before. Newly allocated event loop objects have
this feature disabled.</para>
<para>The first watchdog notification message is sent immediately
when <function>set_event_set_watchdog()</function> is invoked with
a true <parameter>b</parameter> parameter.</para>
<para>The watchdog logic is designed to allow the service manager
to automatically detect services that ceased processing of
incoming events, and thus appear "hung". Watchdog notifications
are sent out only at the beginning of each event loop
iteration. If an event source dispatch function blocks for an
excessively long time and does not return execution to the event
loop quickly, this might hence cause the notification message to
be delayed, and possibly result in abnormal program termination,
as configured in the service unit file.</para>
<para><function>sd_event_get_watchdog()</function> may be used to
determine whether watchdog support was previously requested by a
call to <function>sd_event_set_watchdog()</function> with a true
<parameter>b</parameter> parameter and successfully
enabled.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_set_watchdog()</function> and
<function>sd_event_get_watchdog()</function> return a non-zero
positive integer if the service manager requested watchdog support
and watchdog support was successfully enabled. They return zero if
the service manager did not request watchdog support, or if
watchdog support was explicitly disabled with a false
<parameter>b</parameter> parameter. On failure, they return a
negative errno-style error
code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>The passed event loop object was invalid.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_watchdog_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

100
man/sd_event_source_get_event.xml Normal file
View File

@ -0,0 +1,100 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_get_event" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_get_event</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_get_event</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_get_event</refname>
<refpurpose>Retrieve the event loop of an event source</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>sd_event* <function>sd_event_source_get_event</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_get_event()</function> may be used
to retrieve the event loop object the event source object specified
as <parameter>source</parameter> is associated with. The event
loop object is specified when creating an event source object with
calls such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_source_get_event()</function>
returns the associated event loop object. On failure, it returns
NULL.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

167
man/sd_event_source_get_pending.xml Normal file
View File

@ -0,0 +1,167 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_get_pending</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_get_pending</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_get_pending</refname>
<refpurpose>Determine pending state of event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_source_get_pending</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_get_pending()</function> may be
used to determine whether the event source object specified as
<parameter>source</parameter> has seen events but has not been
dispatched yet (and thus is marked "pending").</para>
<para>Event source objects initially are not marked pending, when
they are created with calls such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
with the exception of those created with
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
which are immediately marked pending, and
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for which the "pending" concept is not defined. For details see
the respective manual pages.</para>
<para>In each event loop iteration one event source of those
marked pending is dispatched, in the order defined by the event
source priority, as set with
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>For I/O event sources, as created with
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
the call
<citerefentry><refentrytitle>sd_event_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry>
may be used to query the type of event pending in more
detail.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success,
<function>sd_event_source_get_pending()</function> returns an
integer greater than zero when the event source is marked pending,
and zero when the event source is not marked pending. On failure,
it returns a negative errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>source</parameter> is not a valid
pointer to an <structname>sd_event_source</structname>
object.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EDOM</constant></term>
<listitem><para><parameter>source</parameter> refers to an
event source object created with
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESTALE</constant></term>
<listitem><para>The event loop is already terminated.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

170
man/sd_event_source_set_description.xml Normal file
View File

@ -0,0 +1,170 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2014 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_set_description</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>More text</contrib>
<firstname>Zbigniew</firstname>
<surname>Jędrzejewski-Szmek</surname>
<email>zbyszek@in.waw.pl</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_set_description</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_set_description</refname>
<refname>sd_event_source_get_description</refname>
<refpurpose>Set or retrieve descriptive names of event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_source_set_description</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>const char *<parameter>description</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_description</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>const char **<parameter>description</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_set_description()</function> may
be used to set an arbitrary descriptive name for the event source
object specified as <parameter>source</parameter>. This name will
be used in debugging messages generated by
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for this event source, and may be queried using
<function>sd_event_source_get_description()</function> for
debugging purposes. The <parameter>description</parameter> parameter shall
point to a <constant>NUL</constant>-terminated string or be
<constant>NULL</constant>. In the latter case, the descriptive
name will be unset. The string is copied internally, hence the
<parameter>description</parameter> argument is not referenced
after the function returns.</para>
<para><function>sd_event_source_get_description()</function> may
be used to query the current descriptive name assigned to the
event source object <parameter>source</parameter>. It returns a
pointer to the current name in <parameter>description</parameter>,
stored in memory internal to the event source. The memory is
invalidated when the event source is destroyed or the descriptive
name is changed.</para>
<para>Event source objects generally have no description set when
they are created, except for UNIX signal event sources created
with
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
whose descriptive name is initialized to the signal's C constant
name (e.g. <literal>SIGINT</literal> or
<literal>SIGTERM</literal>).</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_source_set_description()</function> and
<function>sd_event_source_get_description()</function> return a
non-negative integer. On failure, they return a negative
errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>source</parameter> is not a valid
pointer to an <structname>sd_event_source</structname>
object or the <parameter>description</parameter> argument for
<function>sd_event_source_get_description()</function> is
<constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory to copy the
name.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENXIO</constant></term>
<listitem><para>No name was set for the event
source.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

179
man/sd_event_source_set_enabled.xml Normal file
View File

@ -0,0 +1,179 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_set_enabled" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_set_enabled</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_set_enabled</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_set_enabled</refname>
<refname>sd_event_source_get_enabled</refname>
<refname>SD_EVENT_ON</refname>
<refname>SD_EVENT_OFF</refname>
<refname>SD_EVENT_ONESHOT</refname>
<refpurpose>Enable or disable event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>enum</token> {
<constant>SD_EVENT_OFF</constant> = 0,
<constant>SD_EVENT_ON</constant> = 1,
<constant>SD_EVENT_ONESHOT</constant> = -1,
};</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_source_set_enabled</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>int <parameter>enabled</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_enabled</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>int *<parameter>enabled</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_set_enabled()</function> may be
used to enable or disable the event source object specified as
<parameter>source</parameter>. The <parameter>enabled</parameter>
parameter takes one of <constant>SD_EVENT_ON</constant> (to
enable), <constant>SD_EVENT_OFF</constant> (to disable) or
<constant>SD_EVENT_ONESHOT</constant>. If invoked with
<constant>SD_EVENT_ONESHOT</constant> the event source will be
enabled but automatically reset to
<constant>SD_EVENT_OFF</constant> after the event source was
dispatched once.</para>
<para>Event sources that are disabled will not result in event
loop wakeups and will not be dispatched, until they are enabled
again.</para>
<para><function>sd_event_source_get_enabled()</function> may be
used to query whether the event source object
<parameter>source</parameter> is currently enabled or not. It
returns the enablement state in
<parameter>enabled</parameter>.</para>
<para>Event source objects are enabled when they are first created
with calls such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. However,
depending on the event source type they are enabled continously
(<constant>SD_EVENT_ON</constant>) or only for a single invocation
of the event source handler
(<constant>SD_EVENT_ONESHOT</constant>). For details see the
respective manual pages.</para>
<para>As event source objects stay active and may be dispatched as
long as there is at least one reference to them, in many cases it
is a good idea to combine a call to
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
with a prior call to
<function>sd_event_source_set_enabled()</function> with
<constant>SD_EVENT_OFF</constant>, to ensure the event source is
not dispatched again until all other remaining references are dropped.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, <function>sd_event_source_set_enabled()</function> and
<function>sd_event_source_get_enabled()</function> return a
non-negative integer. On failure, they return a negative
errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>source</parameter> is not a valid
pointer to an <structname>sd_event_source</structname>
object.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

171
man/sd_event_source_set_prepare.xml Normal file
View File

@ -0,0 +1,171 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_set_prepare" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_set_prepare</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_set_prepare</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_set_prepare</refname>
<refpurpose>Set a preparation callback for event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_source_set_prepare</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>sd_event_handler_t <parameter>callback</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_set_prepare()</function> may be
used to set a prepartion callback for the event source object
specified as <parameter>source</parameter>. The callback function
specified as <parameter>callback</parameter> will be invoked
immediately before the event loop goes to sleep to wait for
incoming events. It is invoked with the user data pointer passed
when the event source was created. The callback function may be
used to reconfigure the precise events to wait for. If the
<parameter>callback</parameter> parameter is passed as NULL the
callback function is reset. </para>
<para>Event source objects have no preparation callback associated
when they are first created with calls such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
callback functions are supported for all event source types with
the exception of those created with
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
callback functions are dispatched in the order indicated by the
event source's priority field, as set with
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Preparation
callbacks of disabled event sources (see
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
are not invoked.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success,
<function>sd_event_source_set_prepare()</function> returns a
non-negative integer. On failure, it returns a negative
errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>source</parameter> is not a valid
pointer to an <structname>sd_event_source</structname>
object.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESTALE</constant></term>
<listitem><para>The event loop is already terminated.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-EDOM</constant></term>
<listitem><para>The specified event source has been created
with
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

189
man/sd_event_source_set_priority.xml Normal file
View File

@ -0,0 +1,189 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_set_priority" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_set_priority</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_set_priority</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_set_priority</refname>
<refname>sd_event_source_get_priority</refname>
<refname>SD_EVENT_PRIORITY_IMPORTANT</refname>
<refname>SD_EVENT_PRIORITY_NORMAL</refname>
<refname>SD_EVENT_PRIORITY_IDLE</refname>
<refpurpose>Set or retrieve the priority of event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>enum</token> {
<constant>SD_EVENT_SOURCE_IMPORTANT</constant> = -100,
<constant>SD_EVENT_SOURCE_NORMAL</constant> = 0,
<constant>SD_EVENT_SOURCE_IDLE</constant> = 100,
};</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_source_set_priority</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>int64_t <parameter>priority</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_source_get_priority</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>int64_t *<parameter>priority</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_set_priority()</function> may be
used to set the priority for the event source object specified as
<parameter>source</parameter>. The priority is specified as an
arbitrary signed 64bit integer. The priority is initialized to
<constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) when the event
source is allocated with a call such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
and may be changed with this call. If multiple event sources have seen events at the same time, they are dispatched in the order indicated by the
event sources' priorities. Event sources with smaller priority
values are dispatched first. As well-known points of reference,
the constants <constant>SD_EVENT_PRIORITY_IMPORTANT</constant>
(-100), <constant>SD_EVENT_PRIORITY_NORMAL</constant> (0) and
<constant>SD_EVENT_PRIORITY_IDLE</constant> (100) may be used to
indicate event sources that shall be dispatched early, normally or
late. It is recommended to specify priorities based on these
definitions, and relative to them -- however, the full 64bit
signed integer range is available for ordering event
sources.</para>
<para>Priorities define the order in which event sources that have
seen events are dispatched. Care should be taken to ensure that
high-priority event sources (those with negative priority values
assigned) do not cause starvation of low-priority event sources
(those with positive priority values assigned).</para>
<para>The order in which event sources with the same priority are
dispatched is undefined, but the event loop generally tries to
dispatch them in the order it learnt about events on them. As the
backing kernel primitives do not provide accurate information
about the order in which events occured this is not necessarily
reliable. However, it is guaranteed that if events are seen on
multiple same-priority event sources at the same time, each one is
not dispatched again until all others have been dispatched
once. This behaviour guarantees that within each priority
particular event sources do not starve or dominate the event
loop.</para>
<para><function>sd_event_source_get_priority()</function> may be
used to query the current priority assigned to the event source
object <parameter>source</parameter>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success,
<function>sd_event_source_set_priority()</function> and
<function>sd_event_source_get_priority()</function> return a
non-negative integer. On failure, they return a negative
errno-style error code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
<para>Returned errors may indicate the following problems:</para>
<variablelist>
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para><parameter>source</parameter> is not a valid
pointer to an <structname>sd_event_source</structname>
object.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
<listitem><para>Not enough memory.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ESTALE</constant></term>
<listitem><para>The event loop is already terminated.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

119
man/sd_event_source_set_userdata.xml Normal file
View File

@ -0,0 +1,119 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_set_userdata" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_set_userdata</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_set_userdata</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_set_userdata</refname>
<refname>sd_event_source_get_userdata</refname>
<refpurpose>Set or retrieve user data pointer of event sources</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>void* <function>sd_event_source_set_userdata</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void* <function>sd_event_source_get_userdata</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_set_userdata()</function> may be
used to set an arbitrary user data pointer for the event source
object specified as <parameter>source</parameter>. The user data
pointer is usually specified when creating an event source object
with calls such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
and may be updated with this call. The user data pointer is also
passed to all handler callback functions associated with the event
source. The <parameter>userdata</parameter> parameter specifies
the new user data pointer to set, the function returns the
previous user data pointer. Note that <constant>NULL</constant> is
a valid user data pointer.</para>
<para><function>sd_event_source_get_userdata()</function> may be
used to query the current user data pointer assigned to the event
source object <parameter>source</parameter>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success,
<function>sd_event_source_set_userdata()</function> and
<function>sd_event_source_get_userdata()</function> return the
previously set user data pointer. On failure, they return
NULL.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

125
man/sd_event_source_unref.xml Normal file
View File

@ -0,0 +1,125 @@
<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2015 Lennart Poettering
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_source_unref" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_source_unref</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_source_unref</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_source_unref</refname>
<refname>sd_event_source_ref</refname>
<refpurpose>Increase or decrease event source reference counters</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcprototype>
<funcdef>sd_event_source* <function>sd_event_source_unref</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>sd_event_source* <function>sd_event_source_ref</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_source_unref()</function> may be used to
decrement by one the reference counter of the event source object
specified as <parameter>source</parameter>. The reference counter
is initially set to one, when the event source is created with calls
such as
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>
or
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>. When
the reference counter reaches zero it is removed from its event loop
object and destroyed.</para>
<para><function>sd_event_source_ref()</function> may be used
to increase by one the reference counter of the event source object
specified as <parameter>source</parameter>.</para>
<para>Both functions execute no operation if the passed event
source object is <constant>NULL</constant>.</para>
<para>Note that event source objects stay alive and may be
dispatched as long as they have a reference counter greater than
zero. In order to drop a reference of an event source and make
sure the associated event source handler function is not called
anymore it is recommended to combine a call of
<function>sd_event_source_unref()</function> with a prior call to
<function>sd_event_source_set_enabled()</function> with
<constant>SD_EVENT_OFF</constant>.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para><function>sd_event_source_unref()</function> always returns
<constant>NULL</constant>.
<function>sd_event_source_ref()</function> always returns the
event source object passed in.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

271
man/sd_event_wait.xml
View File

@ -21,7 +21,7 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sd_event_wait">
<refentry id="sd_event_wait" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_wait</title>
@ -46,14 +46,32 @@
<refname>sd_event_wait</refname>
<refname>sd_event_prepare</refname>
<refname>sd_event_dispatch</refname>
<refname>sd_event_get_state</refname>
<refname>SD_EVENT_INITIAL</refname>
<refname>SD_EVENT_PREPARING</refname>
<refname>SD_EVENT_ARMED</refname>
<refname>SD_EVENT_PENDING</refname>
<refname>SD_EVENT_RUNNING</refname>
<refname>SD_EVENT_EXITING</refname>
<refname>SD_EVENT_FINISHED</refname>
<refpurpose>Run parts of the libsystemd event loop</refpurpose>
<refpurpose>Low-level event loop operations</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>enum</token> {
<constant>SD_EVENT_INITIAL</constant>,
<constant>SD_EVENT_PREPARING</constant>,
<constant>SD_EVENT_ARMED</constant>,
<constant>SD_EVENT_PENDING</constant>,
<constant>SD_EVENT_RUNNING</constant>,
<constant>SD_EVENT_EXITING</constant>,
<constant>SD_EVENT_FINISHED</constant>,
};</funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>sd_event_prepare</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
@ -62,7 +80,7 @@
<funcprototype>
<funcdef>int <function>sd_event_wait</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>uint64_t <parameter>timeout</parameter></paramdef>
<paramdef>uint64_t <parameter>usec</parameter></paramdef>
</funcprototype>
<funcprototype>
@ -70,66 +88,184 @@
<paramdef>sd_event *<parameter>event</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_get_state</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>Functions described here form parts of an event loop.</para>
<para>The low-level <function>sd_event_prepare()</function>,
<function>sd_event_wait()</function> and
<function>sd_event_dispatch()</function> functions may be used to
execute specific phases of an event loop. See
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>sd_event_loop</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for higher-level functions that execute individual but complete
iterations of an event loop or run it continously.</para>
<para><function>sd_event_prepare</function> checks for pending
<para><function>sd_event_prepare()</function> checks for pending
events and arms necessary timers. If any events are ready to be
processed, it returns a positive value, and the events should be
processed with <function>sd_event_dispatch</function>.
<function>sd_event_dispatch</function> runs a handler for one of
the events from the sources with the highest priority. On success,
<function>sd_event_dispatch</function> returns either 0, which
means that the loop is finished, or a positive value, which means
that the loop is again in the initial state and
<function>sd_event_prepare</function> should be called again.
</para>
processed ("pending"), it returns a positive, non-zero value, and the caller
should process these events with
<function>sd_event_dispatch()</function>.</para>
<para>In case <function>sd_event_prepare</function> returned 0,
<function>sd_event_wait</function> should be called to wait for
events or a timeout. If any events are ready to be processed, it
returns a positive value, and the events should be processed with
<function>sd_event_dispatch</function>. Otherwise, the loop is
back in the initial state and <function>sd_event_prepare</function>
should be called again.</para>
<para><function>sd_event_dispatch()</function> dispatches the
highest priority event source that has a pending event. On
success, <function>sd_event_dispatch()</function> returns either
zero, which indicates that no further event sources may be
dispatched and exiting of the event loop was requested via
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>;
or a positive non-zero value, which means that an event source was
dispatched and the loop returned to its initial state, and the
caller should initiate the next event loop iteration by invoking
<function>sd_event_prepare()</function> again.</para>
<para>In case <function>sd_event_prepare()</function> returned
zero, <function>sd_event_wait()</function> should be called to
wait for further events or a timeout. If any events are ready to
be processed, it returns a positive, non-zero value, and the
events should be dispatched with
<function>sd_event_dispatch()</function>. Otherwise, the event
loop returned to its initial state and the next event loop
iteration should be initiated by invoking
<function>sd_event_prepare()</function> again.</para>
<para><function>sd_event_get_state()</function> may be used to
determine the state the event loop is currently in. It returns one
of the states described below.</para>
<para>All four functions take, as the first argument, the event
loop object <parameter>event</parameter> that has been created
with <function>sd_event_new()</function>. The timeout for
<function>sd_event_wait()</function> is specified in
<parameter>usec</parameter> in milliseconds. <constant>(uint64_t)
-1</constant> may be used to specify an infinite timeout.</para>
</refsect1>
<refsect1>
<title>State Machine</title>
<para>The event loop knows the following states, that may be
queried with <function>sd_event_get_state()</function>.</para>
<variablelist>
<varlistentry>
<term><constant>SD_EVENT_INITIAL</constant></term>
<listitem><para>The initial state the event loop is in,
before each event loop iteration. Use
<function>sd_event_prepare()</function> to transition the
event loop into the <constant>SD_EVENT_ARMED</constant> or
<constant>SD_EVENT_PENDING</constant> states.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>SD_EVENT_PREPARING</constant></term>
<listitem><para>An event source is currently being prepared,
i.e. the preparation handler is currently being excuted, as
set with
<citerefentry><refentrytitle>sd_event_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
state is only seen in the event source preparation handler
that is invoked from the
<function>sd_event_prepare()</function> call and is
immediately followed by <constant>SD_EVENT_ARMED</constant> or
<constant>SD_EVENT_PENDING</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>SD_EVENT_ARMED</constant></term>
<listitem><para><function>sd_event_prepare()</function> has
been called and no event sources were ready to be
dispatched. Use <function>sd_event_wait()</function> to wait
for new events, and transition into
<constant>SD_EVENT_PENDING</constant> or back into
<constant>SD_EVENT_INITIAL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>SD_EVENT_PENDING</constant></term>
<listitem><para><function>sd_event_prepare()</function> or
<function>sd_event_wait()</function> have been called and
there were event sources with events pending. Use
<function>sd_event_dispatch()</function> to dispatch the
highest priority event source and transition back to
<constant>SD_EVENT_INITIAL</constant>, or
<constant>SD_EVENT_FINISHED</constant>.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>SD_EVENT_RUNNING</constant></term>
<listitem><para>A regular event source is currently being
dispatched. This state is only seen in the event source
handler that is invoked from the
<function>sd_event_dispatch()</function> call, and is
immediately followed by <constant>SD_EVENT_INITIAL</constant>
or <constant>SD_EVENT_FINISHED</constant> as soon the event
source handler returns. Note that during dispatching of exit
event sources the <constant>SD_EVENT_EXITING</constant> state
is seen instead.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>SD_EVENT_EXITING</constant></term>
<listitem><para>Similar to
<constant>SD_EVENT_RUNNING</constant> but is the state in
effect while dispatching exit event sources. It is followed by
<constant>SD_EVENT_INITIAL</constant> or
<constant>SD_EVENT_FINISHED</constant> as soon as the event
handler returns.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>SD_EVENT_FINISHED</constant></term>
<listitem><para>The event loop has exited. All exit event
sources have run. If the event loop is in this state it serves
no purpose anymore, and should be freed.</para></listitem>
</varlistentry>
</variablelist>
<para>A simplified flow chart of the states and the calls to
transition between them is shown below. Note that
<constant>SD_EVENT_PREPARING</constant>,
<constant>SD_EVENT_RUNNING</constant> and
<constant>SD_EVENT_EXITING</constant> are not shown here.</para>
<programlisting>
┌──────────┐
│ initial ├──←←←←←←←←←←←←←←←←←←←─┐
└───┬──────┘ ↑
│ ↑
sd_event_prepare ┌─────────┐ ↑
├ 0 →→→→→→→──┤ armed │ ↑
1 └───┬─────┘ ↑
↓ │ ↑
↓ sd_event_wait ↑
├───←←←←←←←─── 1 ┴─ 0 →→→→→→→─┘
┌───┴──────┐ ↑
│ pending │ ↑
└───┬──────┘ ↑
│ ↑
sd_event_dispatch ↑
↓ ↑
├ 1 ──────────→→→→→→→─────────┘
0
↓
┌───┴──────┐
│ finished │
└──────────┘
INITIAL -&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---&lt;---\
| |
| ^
| |
v ret == 0 |
sd_event_prepare() &gt;---&gt;---&gt;---&gt;---&gt;- ARMED |
| | ^
| ret > 0 | |
| | |
v v ret == 0 |
PENDING &lt;---&lt;---&lt;---&lt;---&lt;---&lt; sd_event_wait() &gt;---&gt;---&gt;--+
| ret > 0 ^
| |
| |
v |
sd_event_dispatch() &gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;---&gt;/
| ret > 0
| ret == 0
|
v
FINISHED
</programlisting>
<para>All three functions take, as the first argument, the event
loop object <parameter>event</parameter> that is created with
<function>sd_event_new</function>. The timeout for
<function>sd_event_wait</function> is specified with
<parameter>timeout</parameter> in milliseconds.
<constant>(uint64_t) -1</constant> may be used to specify an
infinite timeout.</para>
</refsect1>
<refsect1>
@ -137,13 +273,15 @@
<para>On success, these functions return 0 or a positive integer.
On failure, they return a negative errno-style error code. In case
of <function>sd_event_prepare</function> and
<function>sd_event_wait</function>, a positive value means that
events are ready to be processed and 0 means that no events are
ready. In case of <function>sd_event_dispatch</function>, a
positive value means that the loop is again in the initial state
and 0 means the loop is finished. For any of these functions, a
negative return value means the loop must be aborted.</para>
of <function>sd_event_prepare()</function> and
<function>sd_event_wait()</function>, a positive, non-zero return
code indicates that events are ready to be processed and zero
indicates that no events are ready. In case of
<function>sd_event_dispatch()</function>, a positive, non-zero
return code indicates that the event loop returned to its initial
state and zero indicates the event loop has
exited. <function>sd_event_get_state()</function> returns a
positive or zero state on success.</para>
</refsect1>
<refsect1>
@ -156,7 +294,7 @@
<term><constant>-EINVAL</constant></term>
<listitem><para>The <parameter>event</parameter> parameter is
<constant>NULL</constant>.</para></listitem>
invalid or <constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>
@ -185,14 +323,7 @@
<para>Other errors are possible, too.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>Functions described here are available
as a shared library, which can be compiled and linked to with the
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
file.</para>
</refsect1>
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
@ -200,13 +331,15 @@
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
<citerefentry><refentrytitle>sd_event_add_post</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_run</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_prepare</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

8
man/sd_watchdog_enabled.xml
View File

@ -98,6 +98,11 @@
<varname>WatchdogSec=</varname> in service files. See
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para>
<para>Use
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
to enable automatic watchdog support in
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>-based event loops.</para>
</refsect1>
<refsect1>
@ -168,7 +173,8 @@
<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_set_watchdog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
</para>
</refsect1>

24
man/systemd.service.xml
View File

@ -678,8 +678,10 @@
<constant>SIGPIPE</constant>. Exit status definitions can
either be numeric exit codes or termination signal names,
separated by spaces. For example:
<programlisting>SuccessExitStatus=1 2 8
SIGKILL</programlisting> ensures that exit codes 1, 2, 8 and
<programlisting>SuccessExitStatus=1 2 8 SIGKILL</programlisting>
ensures that exit codes 1, 2, 8 and
the termination signal <constant>SIGKILL</constant> are
considered clean service terminations.
</para>
@ -711,14 +713,16 @@
signal names, and are separated by spaces. Defaults to the
empty list, so that, by default, no exit status is excluded
from the configured restart logic. For example:
<programlisting>RestartPreventExitStatus=1 6
SIGABRT</programlisting> ensures that exit codes 1 and 6 and
the termination signal <constant>SIGABRT</constant> will not
result in automatic service restarting. This option may appear
more than once, in which case the list of restart-preventing
statuses is merged. If the empty string is assigned to this
option, the list is reset and all prior assignments of this
option will have no effect.</para></listitem>
<programlisting>RestartPreventExitStatus=1 6 SIGABRT</programlisting>
ensures that exit codes 1 and 6 and the termination signal
<constant>SIGABRT</constant> will not result in automatic
service restarting. This option may appear more than once, in
which case the list of restart-preventing statuses is
merged. If the empty string is assigned to this option, the
list is reset and all prior assignments of this option will
have no effect.</para></listitem>
</varlistentry>
<varlistentry>