1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-22 13:33:56 +03:00

man/sd_event_{add_io,add_time,add_signal,now}: various small fixes

- remove things which are clear from the context
- 0 is a valid descriptor number, hence "positive" → "non-negative"
- "positive" means greater than zero, hence "positive non-zero" → "positive"
- use oxford comma
- reword some things for clarity
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2016-01-04 23:17:21 -05:00
parent ab6f56debf
commit f23e83b156
4 changed files with 117 additions and 121 deletions

View File

@ -120,36 +120,35 @@
returned in the <parameter>source</parameter> parameter. The returned in the <parameter>source</parameter> parameter. The
<parameter>fd</parameter> parameter takes the UNIX file descriptor <parameter>fd</parameter> parameter takes the UNIX file descriptor
to watch, which may refer to a socket, a FIFO, a message queue, a to watch, which may refer to a socket, a FIFO, a message queue, a
serial connection, a character device or any other file descriptor serial connection, a character device, or any other file descriptor
compatible with Linux <citerefentry compatible with Linux
project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The <citerefentry project='man-pages'><refentrytitle>epoll</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
<parameter>events</parameter> parameter takes a bit mask of I/O <parameter>events</parameter> parameter takes a bit mask of events
events to watch the file descriptor for, a combination of the to watch for, a combination of the following event flags:
following event flags: <constant>EPOLLIN</constant>, <constant>EPOLLIN</constant>, <constant>EPOLLOUT</constant>,
<constant>EPOLLOUT</constant>, <constant>EPOLLRDHUP</constant>, <constant>EPOLLRDHUP</constant>, <constant>EPOLLPRI</constant>,
<constant>EPOLLPRI</constant> and <constant>EPOLLET</constant>, and <constant>EPOLLET</constant>, see
see <citerefentry <citerefentry project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
project='man-pages'><refentrytitle>epoll_ctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details. The <parameter>handler</parameter> shall reference a for details. The <parameter>handler</parameter> shall reference a
function to call when the I/O event source is triggered. The function to call when the event source is triggered. The
handler function will be passed the <parameter>userdata</parameter> pointer will be passed to the
<parameter>userdata</parameter> pointer, which may be chosen handler function, and may be chosen freely by the caller. The
freely by the caller. The handler will also be passed the file handler will also be passed the file descriptor the event was seen
descriptor the event was seen on as well as the actual event flags on, as well as the actual event flags. It's generally a subset of
seen. It's generally a subset of the events watched, however may the events watched, however may additionally include
additionally have <constant>EPOLLERR</constant> and <constant>EPOLLERR</constant> and <constant>EPOLLHUP</constant>.
<constant>EPOLLHUP</constant> set.</para> </para>
<para>By default, the I/O event source will stay enabled <para>By default, an event source will stay enabled
continuously (<constant>SD_EVENT_ON</constant>), but this may be continuously (<constant>SD_EVENT_ON</constant>), but this may be
changed with changed with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>. <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
If the handler function returns a negative error code, it will be If the handler function returns a negative error code, it will be
disabled after the invocation, even if the disabled after the invocation, even if the
<constant>SD_EVENT_ON</constant> mode was requested before. Note <constant>SD_EVENT_ON</constant> mode was requested before. Note
that an I/O event source set to <constant>SD_EVENT_ON</constant> will that an event source set to <constant>SD_EVENT_ON</constant> will
fire continuously unless data is read or written to the file fire continuously unless data is read from or written to the file
descriptor in order to reset the mask of events seen. descriptor to reset the mask of events seen.
</para> </para>
<para>Setting the I/O event mask to watch for to 0 does not mean <para>Setting the I/O event mask to watch for to 0 does not mean
@ -164,16 +163,17 @@
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop 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 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 an event source does not fire anymore, even if it is still referenced,
reference to it kept, consider setting the event source to disable the event source using
<constant>SD_EVENT_OFF</constant> with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> with <constant>SD_EVENT_OFF</constant>.</para>
<para>If the second parameter of <para>If the second parameter of
<function>sd_event_add_io()</function> is passed as NULL no <function>sd_event_add_io()</function> is
reference to the event source object is returned. In this case the <constant>NULL</constant> no reference to the event source object
event source is considered "floating", and will be destroyed is returned. In this case the event source is considered
implicitly when the event loop itself is destroyed.</para> "floating", and will be destroyed implicitly when the event loop
itself is destroyed.</para>
<para>It is recommended to use <para>It is recommended to use
<function>sd_event_add_io()</function> only in conjunction with <function>sd_event_add_io()</function> only in conjunction with
@ -181,24 +181,24 @@
ensure that all I/O operations from invoked handlers are properly ensure that all I/O operations from invoked handlers are properly
asynchronous and non-blocking. Using file descriptors without asynchronous and non-blocking. Using file descriptors without
<constant>O_NONBLOCK</constant> might result in unexpected <constant>O_NONBLOCK</constant> might result in unexpected
starving of other event sources. See <citerefentry starvation of other event sources. See
project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry> <citerefentry project='man-pages'><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details on enabling <constant>O_NONBLOCK</constant> mode.</para> for details on enabling <constant>O_NONBLOCK</constant> mode.</para>
<para><function>sd_event_source_get_io_events()</function> retrieves <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 previously with <function>sd_event_add_io()</function>. It takes
the event source object and a pointer to a variable to store the 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 <para><function>sd_event_source_set_io_events()</function>
configured I/O event mask to watch of an I/O event source created previously configures the mask of watched I/O events of an event source created
with <function>sd_event_add_io()</function>. It takes the event previously with <function>sd_event_add_io()</function>. It takes the
source object and the new event mask to set.</para> event source object and the new event mask.</para>
<para><function>sd_event_source_get_io_revents()</function> <para><function>sd_event_source_get_io_revents()</function>
retrieves the I/O event mask of currently seen but undispatched 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 <function>sd_event_add_io()</function>. It takes the event source
object and a pointer to a variable to store the event mask object and a pointer to a variable to store the event mask
in. When called from a handler function on the handler's event in. When called from a handler function on the handler's event
@ -214,15 +214,15 @@
source types, the latter only to I/O event sources.</para> source types, the latter only to I/O event sources.</para>
<para><function>sd_event_source_get_io_fd()</function> retrieves <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 with <function>sd_event_add_io()</function>. It takes the event
source object and returns the positive file descriptor in the return source object and returns the non-negative file descriptor
value, or a negative error number on error (see below).</para> or a negative error number on error (see below).</para>
<para><function>sd_event_source_set_io_fd()</function> <para><function>sd_event_source_set_io_fd()</function>
changes the UNIX file descriptor of an I/O event source created changes the UNIX file descriptor of an I/O event source created
previously with <function>sd_event_add_io()</function>. It takes 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>
<refsect1> <refsect1>
@ -230,13 +230,13 @@
<para>On success, these functions return 0 or a positive <para>On success, these functions return 0 or a positive
integer. On failure, they return a negative errno-style error integer. On failure, they return a negative errno-style error
code. </para> code.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Errors</title> <title>Errors</title>
<para>Returned errors may indicate the following problems:</para> <para>Returned values may indicate the following problems:</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

View File

@ -123,24 +123,23 @@
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop 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 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 an event source does not fire anymore, even if it is still referenced,
reference to it kept, consider setting the event source to disable the event source using
<constant>SD_EVENT_OFF</constant> with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> with <constant>SD_EVENT_OFF</constant>.</para>
<para>If the second parameter of <para>If the second parameter of
<function>sd_event_add_signal()</function> is passed as NULL no <function>sd_event_add_signal()</function> is
reference to the event source object is returned. In this case the <constant>NULL</constant> no reference to the event source object
event source is considered "floating", and will be destroyed is returned. In this case the event source is considered
implicitly when the event loop itself is destroyed.</para> "floating", and will be destroyed implicitly when the event loop
itself is destroyed.</para>
<para><function>sd_event_source_get_signal()</function> retrieves <para><function>sd_event_source_get_signal()</function> returns
the configured UNIX process signal number of a signal event source the configured signal number of an event source created previously
created previously with with <function>sd_event_add_signal()</function>. It takes the
<function>sd_event_add_signal()</function>. It takes the event event source object as the <parameter>source</parameter>
source object as the <parameter>source</parameter>
parameter.</para> parameter.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -148,7 +147,7 @@
<para>On success, these functions return 0 or a positive <para>On success, these functions return 0 or a positive
integer. On failure, they return a negative errno-style error integer. On failure, they return a negative errno-style error
code. </para> code.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -167,7 +166,6 @@
<term><constant>-EINVAL</constant></term> <term><constant>-EINVAL</constant></term>
<listitem><para>An invalid argument has been passed.</para></listitem> <listitem><para>An invalid argument has been passed.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
@ -175,21 +173,18 @@
<listitem><para>A handler is already installed for this <listitem><para>A handler is already installed for this
signal or the signal was not blocked previously.</para></listitem> signal or the signal was not blocked previously.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><constant>-ESTALE</constant></term> <term><constant>-ESTALE</constant></term>
<listitem><para>The event loop is already terminated.</para></listitem> <listitem><para>The event loop is already terminated.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><constant>-ECHILD</constant></term> <term><constant>-ECHILD</constant></term>
<listitem><para>The event loop has been created in a different process.</para></listitem> <listitem><para>The event loop has been created in a different process.</para></listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>

View File

@ -122,31 +122,31 @@
clock identifier, one of <constant>CLOCK_REALTIME</constant>, clock identifier, one of <constant>CLOCK_REALTIME</constant>,
<constant>CLOCK_MONOTONIC</constant>, <constant>CLOCK_MONOTONIC</constant>,
<constant>CLOCK_BOOTTIME</constant>, <constant>CLOCK_BOOTTIME</constant>,
<constant>CLOCK_REALTIME_ALARM</constant> or <constant>CLOCK_REALTIME_ALARM</constant>, or
<constant>CLOCK_BOOTTIME_ALARM</constant>. See <constant>CLOCK_BOOTTIME_ALARM</constant>. See
<citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry> <citerefentry><refentrytitle>timerfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for details regarding the various types of clocks. The for details regarding the various types of clocks. The
<parameter>usec</parameter> parameter takes a time value in <parameter>usec</parameter> parameter specifies the earliest time,
microseconds (µs), relative to the clock's epoch, specifying when in microseconds (µs), relative to the clock's epoch, when
the timer shall elapse the earliest. If a time that already lies the timer shall be triggered. If a time already in the past is
in the past is specified (including 0), the timer source is specified (including <constant>0</constant>), this timer source
dispatched immediately in the next event loop iterations. The "fires" immediately and is ready to be dispatched. The
<parameter>accuracy</parameter> parameter takes an additional <parameter>accuracy</parameter> parameter specifies an additional
accuracy value in µs specifying a time the timer event may be accuracy value in µs specifying how much the timer event may be
delayed. Specify 0 for selecting the default accuracy delayed. Use <constant>0</constant> to select the default accuracy
(250ms). Specify 1µs for most accurate timers. Consider specifying (250ms). Use 1µs for maximum accuracy. Consider specifying
60000000µs or larger (1min) for long-running events that may be 60000000µs (1min) or larger for long-running events that may be
delayed substantially. Picking higher accuracy values allows the 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 power efficiency. The <parameter>handler</parameter> parameter
shall reference a function to call when the timer elapses. The shall reference a function to call when the timer elapses. The
handler function will be passed the handler function will be passed the
<parameter>userdata</parameter> pointer, which may be chosen <parameter>userdata</parameter> pointer, which may be chosen
freely by the caller. The handler is also passed the configured freely by the caller. The handler is also passed the configured
time it was triggered, however it might actually have been called trigger time, even if it is actually called
at a slightly later time, subject to the specified accuracy value, slightly later, subject to the specified accuracy value,
the kernel timer slack (see 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 and additional scheduling latencies. To query the actual time the
handler was called use handler was called use
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
@ -167,22 +167,24 @@
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
but note that the event source is only removed from the event loop 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 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 an event source does not fire anymore, even if it is still referenced,
reference to it kept, consider setting the event source to disable the event source using
<constant>SD_EVENT_OFF</constant> with <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> with <constant>SD_EVENT_OFF</constant>.</para>
<para>If the second parameter of <para>If the second parameter of
<function>sd_event_add_time()</function> is passed as NULL no <function>sd_event_add_time()</function> is
reference to the event source object is returned. In this case the <constant>NULL</constant> no reference to the event source object
event source is considered "floating", and will be destroyed is returned. In this case the event source is considered
implicitly when the event loop itself is destroyed.</para> "floating", and will be destroyed implicitly when the event loop
itself is destroyed.</para>
<para>If the <parameter>handler</parameter> to <para>If the <parameter>handler</parameter> to
<function>sd_event_add_time()</function> is passed as NULL, and <function>sd_event_add_time()</function> is
the event source fires, this will be considered a request to exit <constant>NULL</constant>, and the event source fires, this will
the event loop. In this case, the <parameter>userdata</parameter> be considered a request to exit the event loop. In this case, the
parameter, cast to an integer is used for the exit code passed to <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> <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and <para>Use <constant>CLOCK_BOOTTIME_ALARM</constant> and
@ -192,7 +194,7 @@
<para>In order to set up relative timers (that is, relative to the <para>In order to set up relative timers (that is, relative to the
current time), retrieve the current time via current time), retrieve the current time via
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <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 the <parameter>usec</parameter> parameter to
<function>sd_event_add_time()</function>.</para> <function>sd_event_add_time()</function>.</para>
@ -212,30 +214,30 @@
latency will keep accumulating on the timer.</para> latency will keep accumulating on the timer.</para>
<para><function>sd_event_source_get_time()</function> retrieves <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 previously with <function>sd_event_add_time()</function>. It takes
the event source object and a pointer to a variable to store the 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 <para><function>sd_event_source_set_time()</function> changes the
configured time value of a timer event source created previously time of an event source created previously with
with <function>sd_event_add_time()</function>. It takes the event <function>sd_event_add_time()</function>. It takes the event
source object and a time relative to the selected clock's source object and a time relative to the selected clock's epoch,
epoch, in µs.</para> in µs.</para>
<para><function>sd_event_source_get_time_accuracy()</function> <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 created previously with <function>sd_event_add_time()</function>. It
takes the event source object and a pointer to a variable to store 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> <para><function>sd_event_source_set_time_accuracy()</function>
changes the configured accuracy of a timer event source created changes the configured accuracy of a timer event source created
previously with <function>sd_event_add_time()</function>. It takes 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> <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 previously with <function>sd_event_add_time()</function>. It takes
the event source object and a pointer to a variable to store the the event source object and a pointer to a variable to store the
clock identifier in.</para> clock identifier in.</para>
@ -252,7 +254,7 @@
<refsect1> <refsect1>
<title>Errors</title> <title>Errors</title>
<para>Returned errors may indicate the following problems:</para> <para>Returned values may indicate the following problems:</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>

View File

@ -65,45 +65,44 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para><function>sd_event_now()</function> returns the timestamp <para><function>sd_event_now()</function> returns the time when
the most recent event loop iteration began. This timestamp is the most recent event loop iteration began. A timestamp
taken right after returning from the event sleep, and before is taken right after returning from the event sleep, and before
dispatching any event sources. The <parameter>event</parameter> 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 from. The <parameter>clock</parameter> parameter specifies the clock to
retrieve the timestamp for, and is one of 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_REALTIME_ALARM</constant>),
<constant>CLOCK_MONOTONIC</constant> or <constant>CLOCK_MONOTONIC</constant>, or
<constant>CLOCK_BOOTTIME</constant> (or its equivalent <constant>CLOCK_BOOTTIME</constant> (or equivalently
<constant>CLOCK_BOOTTIME_ALARM</constant>), see <citerefentry <constant>CLOCK_BOOTTIME_ALARM</constant>), see
project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry> <citerefentry project='man-pages'><refentrytitle>clock_gettime</refentrytitle><manvolnum>2</manvolnum></citerefentry>
for more information on the various clocks. The retrieved for more information on the various clocks. The retrieved
timestamp is stored in the <parameter>usec</parameter> parameter, timestamp is stored in the <parameter>usec</parameter> parameter,
in µs since the clock's epoch. If this function is invoked before 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 reported by <function>clock_gettime()</function>. To distinguish
this case from a regular invocation the return value will be this case from a regular invocation the return value will be
positive non-zero in this case, while it is zero when the returned positive, and zero when the returned timestamp refers to an actual
timestamp refers to the actual event loop iteration.</para> event loop iteration.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Return Value</title> <title>Return Value</title>
<para>If the first event loop iteration has not run yet <para>If the first event loop iteration has not run yet
<function>sd_event_now()</function> returns the requested <function>sd_event_now()</function> writes current time to
timestamp in <parameter>usec</parameter> and returns a positive, <parameter>usec</parameter> and returns a positive return value.
non-zero return value. Otherwise, on success it will return the Otherwise, it will write the requested timestamp to <parameter>usec</parameter>
iteration's timestamp in <parameter>usec</parameter> and 0 as and return 0. On failure, the call returns a negative errno-style
return value. On failure, the call returns a negative errno-style
error code.</para> error code.</para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Errors</title> <title>Errors</title>
<para>Returned errors may indicate the following problems:</para> <para>Returned values may indicate the following problems:</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>