chiark / gitweb /
man: use unicode ellipsis in more places
[elogind.git] / man / sd_event_source_get_pending.xml
1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of elogind.
7
8   Copyright 2015 Lennart Poettering
9
10   elogind is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   elogind is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with elogind; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude">
25
26   <refentryinfo>
27     <title>sd_event_source_get_pending</title>
28     <productname>elogind</productname>
29
30     <authorgroup>
31       <author>
32         <contrib>Developer</contrib>
33         <firstname>Lennart</firstname>
34         <surname>Poettering</surname>
35         <email>lennart@poettering.net</email>
36       </author>
37     </authorgroup>
38   </refentryinfo>
39
40   <refmeta>
41     <refentrytitle>sd_event_source_get_pending</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
46     <refname>sd_event_source_get_pending</refname>
47
48     <refpurpose>Determine pending state of event sources</refpurpose>
49   </refnamediv>
50
51   <refsynopsisdiv>
52     <funcsynopsis>
53       <funcsynopsisinfo>#include &lt;elogind/sd-event.h&gt;</funcsynopsisinfo>
54
55       <funcprototype>
56         <funcdef>int <function>sd_event_source_get_pending</function></funcdef>
57         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
58       </funcprototype>
59
60     </funcsynopsis>
61   </refsynopsisdiv>
62
63   <refsect1>
64     <title>Description</title>
65
66     <para><function>sd_event_source_get_pending()</function> may be
67     used to determine whether the event source object specified as
68     <parameter>source</parameter> has seen events but has not been
69     dispatched yet (and thus is marked "pending").</para>
70
71     <para>Event source objects initially are not marked pending, when
72     they are created with calls such as
73     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
74     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
75     with the exception of those created with
76     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
77     which are immediately marked pending, and
78     <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
79     for which the "pending" concept is not defined. For details see
80     the respective manual pages.</para>
81
82     <para>In each event loop iteration one event source of those
83     marked pending is dispatched, in the order defined by the event
84     source priority, as set with
85     <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
86
87     <para>For I/O event sources, as created with
88     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
89     the call
90     <citerefentry><refentrytitle>sd_event_source_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry>
91     may be used to query the type of event pending in more
92     detail.</para>
93
94   </refsect1>
95
96   <refsect1>
97     <title>Return Value</title>
98
99     <para>On success,
100     <function>sd_event_source_get_pending()</function> returns an
101     integer greater than zero when the event source is marked pending,
102     and zero when the event source is not marked pending. On failure,
103     it returns a negative errno-style error code.</para>
104   </refsect1>
105
106   <refsect1>
107     <title>Errors</title>
108
109     <para>Returned errors may indicate the following problems:</para>
110
111     <variablelist>
112       <varlistentry>
113         <term><constant>-EINVAL</constant></term>
114
115         <listitem><para><parameter>source</parameter> is not a valid
116         pointer to an <structname>sd_event_source</structname>
117         object.</para></listitem>
118       </varlistentry>
119
120       <varlistentry>
121         <term><constant>-EDOM</constant></term>
122
123         <listitem><para><parameter>source</parameter> refers to an
124         event source object created with
125         <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
126       </varlistentry>
127
128       <varlistentry>
129         <term><constant>-ENOMEM</constant></term>
130
131         <listitem><para>Not enough memory.</para></listitem>
132       </varlistentry>
133
134       <varlistentry>
135         <term><constant>-ESTALE</constant></term>
136
137         <listitem><para>The event loop is already terminated.</para></listitem>
138
139       </varlistentry>
140
141       <varlistentry>
142         <term><constant>-ECHILD</constant></term>
143
144         <listitem><para>The event loop has been created in a different process.</para></listitem>
145
146       </varlistentry>
147
148     </variablelist>
149   </refsect1>
150
151   <xi:include href="libelogind-pkgconfig.xml" />
152
153   <refsect1>
154     <title>See Also</title>
155
156     <para>
157       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
158       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
159       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
160       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
161       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
162       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
163       <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
164     </para>
165   </refsect1>
166
167 </refentry>