Merge pull request #2373 from keszybz/man-api-build-3

Man page grammar and build tweaks v3
This commit is contained in:
Daniel Mack 2016-01-19 20:44:58 +01:00
commit d619a0c4a5
6 changed files with 125 additions and 139 deletions

View File

@ -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

View File

@ -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]))
])

View File

@ -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>

View File

@ -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>

View File

@ -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>

View File

@ -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>