summaryrefslogtreecommitdiff
path: root/man/sd_event_run.xml
diff options
context:
space:
mode:
authorLennart Poettering <lennart@poettering.net>2015-11-19 23:38:54 +0100
committerLennart Poettering <lennart@poettering.net>2015-11-19 23:38:54 +0100
commitdc83f27a7cf03757dec11a69ec18504ad4ea8f89 (patch)
tree54af47fe95cdaa44ea4f0e3c0c3482e40c46edc3 /man/sd_event_run.xml
parent0be6c2f617732902921d42bb0705f016b2838aba (diff)
man: fully document sd-event interfaces
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.
Diffstat (limited to 'man/sd_event_run.xml')
-rw-r--r--man/sd_event_run.xml95
1 files changed, 51 insertions, 44 deletions
diff --git a/man/sd_event_run.xml b/man/sd_event_run.xml
index 06236fcd1a..5b68959165 100644
--- a/man/sd_event_run.xml
+++ b/man/sd_event_run.xml
@@ -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_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_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> 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>