diff options
| -rw-r--r-- | man/sd_event_add_io.xml | 92 | ||||
| -rw-r--r-- | man/sd_event_add_signal.xml | 35 | ||||
| -rw-r--r-- | man/sd_event_add_time.xml | 80 | ||||
| -rw-r--r-- | man/sd_event_now.xml | 35 |
4 files changed, 119 insertions, 123 deletions
diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index eeb406ba5b..c3749164cd 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -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> - - <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 @@ -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> diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index a2aabd3c1a..e98f1d2682 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -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> - - <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> @@ -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> diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index b58d740bd8..142fa80f8f 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -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> diff --git a/man/sd_event_now.xml b/man/sd_event_now.xml index 58d7375eac..054aff3ac6 100644 --- a/man/sd_event_now.xml +++ b/man/sd_event_now.xml @@ -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> |