mirror of
https://github.com/systemd/systemd.git
synced 2024-11-27 12:13:33 +08:00
Merge pull request #2373 from keszybz/man-api-build-3
Man page grammar and build tweaks v3
This commit is contained in:
Daniel Mack
commit
d619a0c4a5
24
Makefile.am
24
Makefile.am
@ -694,29 +694,27 @@ man_MANS = \
|
||||
|
||||
noinst_DATA += \
|
||||
$(HTML_FILES) \
|
||||
$(HTML_ALIAS)
|
||||
$(HTML_ALIAS) \
|
||||
docs/html/man
|
||||
endif
|
||||
|
||||
CLEANFILES += \
|
||||
$(man_MANS) \
|
||||
$(HTML_FILES) \
|
||||
$(HTML_ALIAS)
|
||||
$(HTML_ALIAS) \
|
||||
docs/html/man
|
||||
|
||||
docs/html/man:
|
||||
$(AM_V_at)$(MKDIR_P) $(dir $@)
|
||||
$(AM_V_LN)$(LN_S) -f ../../man $@
|
||||
|
||||
noinst_DATA += \
|
||||
docs/html/man
|
||||
|
||||
CLEANFILES += \
|
||||
docs/html/man
|
||||
|
||||
if HAVE_PYTHON
|
||||
man/index.html: man/systemd.index.html
|
||||
$(AM_V_LN)$(LN_S) -f systemd.index.html $@
|
||||
|
||||
if HAVE_PYTHON
|
||||
noinst_DATA += \
|
||||
man/index.html
|
||||
endif
|
||||
|
||||
CLEANFILES += \
|
||||
man/index.html
|
||||
@ -745,11 +743,6 @@ CLEANFILES += \
|
||||
man/systemd.index.xml \
|
||||
man/systemd.directives.xml
|
||||
|
||||
|
||||
endif
|
||||
|
||||
endif
|
||||
|
||||
EXTRA_DIST += \
|
||||
$(filter-out man/systemd.directives.xml man/systemd.index.xml,$(XML_FILES)) \
|
||||
tools/make-man-index.py \
|
||||
@ -6025,7 +6018,6 @@ EXTRA_DIST += \
|
||||
$(polkitpolicy_in_in_files)
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
if ENABLE_MANPAGES
|
||||
man/custom-entities.ent: configure.ac
|
||||
$(AM_V_GEN)$(MKDIR_P) $(dir $@)
|
||||
$(AM_V_GEN)(echo '<?xml version="1.0" encoding="utf-8" ?>' && \
|
||||
@ -6073,8 +6065,6 @@ define html-alias
|
||||
$(AM_V_LN)$(LN_S) -f $(notdir $<) $@
|
||||
endef
|
||||
|
||||
endif
|
||||
|
||||
EXTRA_DIST += \
|
||||
man/custom-html.xsl \
|
||||
man/custom-man.xsl
|
||||
|
||||
@ -1301,9 +1301,9 @@ AM_CONDITIONAL(ENABLE_HWDB, [test x$enable_hwdb = xyes])
|
||||
# ------------------------------------------------------------------------------
|
||||
have_manpages=no
|
||||
AC_ARG_ENABLE(manpages, AS_HELP_STRING([--disable-manpages], [disable manpages]))
|
||||
AC_PATH_PROG([XSLTPROC], [xsltproc])
|
||||
AS_IF([test "x$enable_manpages" != xno], [
|
||||
have_manpages=yes
|
||||
AC_PATH_PROG([XSLTPROC], [xsltproc])
|
||||
AS_IF([test -z "$XSLTPROC"],
|
||||
AC_MSG_ERROR([*** xsltproc is required for man pages]))
|
||||
])
|
||||
|
||||
@ -120,36 +120,35 @@
|
||||
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>
|
||||
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, 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
|
||||
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
|
||||
@ -164,16 +163,17 @@
|
||||
<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
|
||||
@ -181,24 +181,24 @@
|
||||
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
|
||||
@ -214,15 +214,15 @@
|
||||
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>
|
||||
@ -230,13 +230,13 @@
|
||||
|
||||
<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>
|
||||
|
||||
@ -123,24 +123,23 @@
|
||||
<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>
|
||||
<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> 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>
|
||||
<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>
|
||||
@ -148,7 +147,7 @@
|
||||
|
||||
<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>
|
||||
@ -167,7 +166,6 @@
|
||||
<term><constant>-EINVAL</constant></term>
|
||||
|
||||
<listitem><para>An invalid argument has been passed.</para></listitem>
|
||||
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
@ -175,21 +173,18 @@
|
||||
|
||||
<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>
|
||||
|
||||
@ -122,31 +122,31 @@
|
||||
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>
|
||||
@ -167,22 +167,24 @@
|
||||
<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
|
||||
@ -192,7 +194,7 @@
|
||||
<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>
|
||||
|
||||
@ -212,30 +214,30 @@
|
||||
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>
|
||||
@ -252,7 +254,7 @@
|
||||
<refsect1>
|
||||
<title>Errors</title>
|
||||
|
||||
<para>Returned errors may indicate the following problems:</para>
|
||||
<para>Returned values may indicate the following problems:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
|
||||
@ -65,45 +65,44 @@
|
||||
<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>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user