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>
+ 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 events
+ to watch 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
+ function to call when the event source is triggered. The
+ <parameter>userdata</parameter> pointer will be passed to the
+ handler function, and 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. It's generally a subset of
+ the events watched, however may additionally include
+ <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>.
+ </para>
+
+ <para>By default, an event source will stay enabled
continuously (<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 continuously unless data is read or written to the file
- descriptor in order to reset the mask of events seen.
+ that an event source set to <constant>SD_EVENT_ON</constant> will
+ fire continuously unless data is read from or written to the file
+ descriptor to reset the mask of events seen.
</para>
<para>Setting the I/O event mask to watch for to 0 does not mean
<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>
+ an event source does not fire anymore, even if it is still referenced,
+ disable the event source using
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ with <constant>SD_EVENT_OFF</constant>.</para>
<para>If 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>
+ <function>sd_event_add_io()</function> is
+ <constant>NULL</constant> 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
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>
+ starvation 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
+ the configured mask of watched I/O events of an 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>
+ 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_set_io_events()</function>
+ configures the mask of watched I/O events of an event source created
+ previously with <function>sd_event_add_io()</function>. It takes the
+ event source object and the new event mask.</para>
<para><function>sd_event_source_get_io_revents()</function>
retrieves the I/O event mask of currently seen but undispatched
- events from an I/O event source created previously with
+ events from an 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 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
+ the UNIX file descriptor of an 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>
+ source object and returns the non-negative file descriptor
+ 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>
+ the event source object and the new file descriptor.</para>
</refsect1>
<refsect1>
<para>On success, these functions return 0 or a positive
integer. On failure, they return a negative errno-style error
- code. </para>
+ code.</para>
</refsect1>
<refsect1>
<title>Errors</title>
- <para>Returned errors may indicate the following problems:</para>
+ <para>Returned values may indicate the following problems:</para>
<variablelist>
<varlistentry>
<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>
+ an event source does not fire anymore, even if it is still referenced,
+ disable the event source using
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ with <constant>SD_EVENT_OFF</constant>.</para>
<para>If 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 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>
+ <function>sd_event_add_signal()</function> is
+ <constant>NULL</constant> 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> returns
+ the configured signal number of an 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>
<refsect1>
<para>On success, these functions return 0 or a positive
integer. On failure, they return a negative errno-style error
- code. </para>
+ code.</para>
</refsect1>
<refsect1>
<term><constant>-EINVAL</constant></term>
<listitem><para>An invalid argument has been passed.</para></listitem>
-
</varlistentry>
<varlistentry>
<listitem><para>A handler is already installed for this
signal or the signal was not blocked previously.</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>
clock identifier, one of <constant>CLOCK_REALTIME</constant>,
<constant>CLOCK_MONOTONIC</constant>,
<constant>CLOCK_BOOTTIME</constant>,
- <constant>CLOCK_REALTIME_ALARM</constant> or
+ <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 (µ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 µ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
+ <parameter>usec</parameter> parameter specifies the earliest time,
+ in microseconds (µs), relative to the clock's epoch, when
+ the timer shall be triggered. If a time already in the past is
+ specified (including <constant>0</constant>), this timer source
+ "fires" immediately and is ready to be dispatched. The
+ <parameter>accuracy</parameter> parameter specifies an additional
+ accuracy value in µs specifying how much the timer event may be
+ delayed. Use <constant>0</constant> to select the default accuracy
+ (250ms). Use 1µs for maximum accuracy. Consider specifying
+ 60000000µs (1min) or larger for long-running events that may be
delayed substantially. Picking higher accuracy values allows the
- system to coalesce timer events more aggressively, thus improving
+ system to coalesce timer events more aggressively, improving
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,
+ trigger time, even if it is actually called
+ slightly later, subject to the specified accuracy value,
the kernel timer slack (see
- <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>)
+ <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>),
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>
<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>
+ an event source does not fire anymore, even if it is still referenced,
+ disable the event source using
+ <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ with <constant>SD_EVENT_OFF</constant>.</para>
<para>If 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>
+ <function>sd_event_add_time()</function> is
+ <constant>NULL</constant> 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
+ <function>sd_event_add_time()</function> is
+ <constant>NULL</constant>, 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
<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
+ add the desired timespan to it, and use the result as
the <parameter>usec</parameter> parameter to
<function>sd_event_add_time()</function>.</para>
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
+ the configured time value of an 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, relative to the selected clock's epoch, in µs in.</para>
+ time in, relative to the selected clock's epoch, in µs.</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 µs.</para>
+ time of an 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 µs.</para>
<para><function>sd_event_source_get_time_accuracy()</function>
- retrieves the configured accuracy value of a timer event source
+ retrieves the configured accuracy value of a 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 µs in.</para>
+ the accuracy in. The accuracy is specified in µs.</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 µs.</para>
+ the event source object and accuracy, in µs.</para>
<para><function>sd_event_source_get_time_clock()</function>
- retrieves the configured clock of a timer event source created
+ retrieves the configured clock of a 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>
<title>Errors</title>
- <para>Returned errors may indicate the following problems:</para>
+ <para>Returned values may indicate the following problems:</para>
<variablelist>
<varlistentry>
<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 returning from the event sleep, and before
+ <para><function>sd_event_now()</function> returns the time when
+ the most recent event loop iteration began. A timestamp
+ is taken right 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
+ parameter specifies the event 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</constant> (or equivalently
<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>
+ <constant>CLOCK_MONOTONIC</constant>, or
+ <constant>CLOCK_BOOTTIME</constant> (or equivalently
+ <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
+ 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>
+ positive, and zero when the returned timestamp refers to an 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
+ <function>sd_event_now()</function> writes current time to
+ <parameter>usec</parameter> and returns a positive return value.
+ Otherwise, it will write the requested timestamp to <parameter>usec</parameter>
+ and return 0. 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>
+ <para>Returned values may indicate the following problems:</para>
<variablelist>
<varlistentry>
projects / platform / upstream / systemd.git / commitdiff