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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2015 Lennart Poettering
  11 -->
  12
  13 <refentry id="sd_event_source_get_pending" xmlns:xi="http://www.w3.org/2001/XInclude">
  14
  15   <refentryinfo>
  16     <title>sd_event_source_get_pending</title>
  17     <productname>systemd</productname>
  18
  19     <authorgroup>
  20       <author>
  21         <contrib>Developer</contrib>
  22         <firstname>Lennart</firstname>
  23         <surname>Poettering</surname>
  24         <email>lennart@poettering.net</email>
  25       </author>
  26     </authorgroup>
  27   </refentryinfo>
  28
  29   <refmeta>
  30     <refentrytitle>sd_event_source_get_pending</refentrytitle>
  31     <manvolnum>3</manvolnum>
  32   </refmeta>
  33
  34   <refnamediv>
  35     <refname>sd_event_source_get_pending</refname>
  36
  37     <refpurpose>Determine pending state of event sources</refpurpose>
  38   </refnamediv>
  39
  40   <refsynopsisdiv>
  41     <funcsynopsis>
  42       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  43
  44       <funcprototype>
  45         <funcdef>int <function>sd_event_source_get_pending</function></funcdef>
  46         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  47       </funcprototype>
  48
  49     </funcsynopsis>
  50   </refsynopsisdiv>
  51
  52   <refsect1>
  53     <title>Description</title>
  54
  55     <para><function>sd_event_source_get_pending()</function> may be
  56     used to determine whether the event source object specified as
  57     <parameter>source</parameter> has seen events but has not been
  58     dispatched yet (and thus is marked "pending").</para>
  59
  60     <para>Event source objects initially are not marked pending, when
  61     they are created with calls such as
  62     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  63     <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  64     with the exception of those created with
  65     <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  66     which are immediately marked pending, and
  67     <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  68     for which the "pending" concept is not defined. For details see
  69     the respective manual pages.</para>
  70
  71     <para>In each event loop iteration one event source of those
  72     marked pending is dispatched, in the order defined by the event
  73     source priority, as set with
  74     <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  75
  76     <para>For I/O event sources, as created with
  77     <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  78     the call
  79     <citerefentry><refentrytitle>sd_event_source_get_io_revents</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  80     may be used to query the type of event pending in more
  81     detail.</para>
  82
  83   </refsect1>
  84
  85   <refsect1>
  86     <title>Return Value</title>
  87
  88     <para>On success,
  89     <function>sd_event_source_get_pending()</function> returns an
  90     integer greater than zero when the event source is marked pending,
  91     and zero when the event source is not marked pending. On failure,
  92     it returns a negative errno-style error code.</para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Errors</title>
  97
  98     <para>Returned errors may indicate the following problems:</para>
  99
 100     <variablelist>
 101       <varlistentry>
 102         <term><constant>-EINVAL</constant></term>
 103
 104         <listitem><para><parameter>source</parameter> is not a valid
 105         pointer to an <structname>sd_event_source</structname>
 106         object.</para></listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term><constant>-EDOM</constant></term>
 111
 112         <listitem><para><parameter>source</parameter> refers to an
 113         event source object created with
 114         <citerefentry><refentrytitle>sd_event_add_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><constant>-ENOMEM</constant></term>
 119
 120         <listitem><para>Not enough memory.</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><constant>-ESTALE</constant></term>
 125
 126         <listitem><para>The event loop is already terminated.</para></listitem>
 127
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><constant>-ECHILD</constant></term>
 132
 133         <listitem><para>The event loop has been created in a different process.</para></listitem>
 134
 135       </varlistentry>
 136
 137     </variablelist>
 138   </refsect1>
 139
 140   <xi:include href="libsystemd-pkgconfig.xml" />
 141
 142   <refsect1>
 143     <title>See Also</title>
 144
 145     <para>
 146       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 147       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 148       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 149       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 150       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 151       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 152       <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 153     </para>
 154   </refsect1>
 155
 156 </refentry>