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 source parameter. The fd 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 epoll7. The - events parameter takes a bit mask of I/O - events to watch the file descriptor for, a combination of the - following event flags: EPOLLIN, - EPOLLOUT, EPOLLRDHUP, - EPOLLPRI and EPOLLET, - see epoll_ctl2 + serial connection, a character device, or any other file descriptor + compatible with Linux + epoll7. The + events parameter takes a bit mask of events + to watch for, a combination of the following event flags: + EPOLLIN, EPOLLOUT, + EPOLLRDHUP, EPOLLPRI, + and EPOLLET, see + epoll_ctl2 for details. The handler shall reference a - function to call when the I/O event source is triggered. The - handler function will be passed the - userdata 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 EPOLLERR and - EPOLLHUP set. + function to call when the event source is triggered. The + userdata 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 + EPOLLERR and EPOLLHUP. + - By default, the I/O event source will stay enabled + By default, an event source will stay enabled continuously (SD_EVENT_ON), but this may be changed with sd_event_source_set_enabled3. If the handler function returns a negative error code, it will be disabled after the invocation, even if the SD_EVENT_ON mode was requested before. Note - that an I/O event source set to SD_EVENT_ON 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 SD_EVENT_ON will + fire continuously unless data is read from or written to the file + descriptor to reset the mask of events seen. Setting the I/O event mask to watch for to 0 does not mean @@ -164,16 +163,17 @@ sd_event_source_unref3, 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 - SD_EVENT_OFF with - sd_event_source_set_enabled3. + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. If the second parameter of - sd_event_add_io() 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. + sd_event_add_io() is + 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. It is recommended to use sd_event_add_io() 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 O_NONBLOCK might result in unexpected - starving of other event sources. See fcntl2 + starvation of other event sources. See + fcntl2 for details on enabling O_NONBLOCK mode. sd_event_source_get_io_events() 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 sd_event_add_io(). It takes the event source object and a pointer to a variable to store the - event mask in. + mask in. - sd_event_source_set_io_events() changes the - configured I/O event mask to watch of an I/O event source created previously - with sd_event_add_io(). It takes the event - source object and the new event mask to set. + sd_event_source_set_io_events() + configures the mask of watched I/O events of an event source created + previously with sd_event_add_io(). It takes the + event source object and the new event mask. sd_event_source_get_io_revents() 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 sd_event_add_io(). 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. sd_event_source_get_io_fd() retrieves - the UNIX file descriptor of an I/O event source created previously + the UNIX file descriptor of an event source created previously with sd_event_add_io(). 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). + source object and returns the non-negative file descriptor + or a negative error number on error (see below). sd_event_source_set_io_fd() changes the UNIX file descriptor of an I/O event source created previously with sd_event_add_io(). It takes - the event source object and the new file descriptor to set. + the event source object and the new file descriptor. @@ -230,13 +230,13 @@ On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. + code. Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: 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 @@ sd_event_source_unref3, 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 - SD_EVENT_OFF with - sd_event_source_set_enabled3. + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. If the second parameter of - sd_event_add_signal() 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. + sd_event_add_signal() is + 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. - sd_event_source_get_signal() retrieves - the configured UNIX process signal number of a signal event source - created previously with - sd_event_add_signal(). It takes the event - source object as the source + sd_event_source_get_signal() returns + the configured signal number of an event source created previously + with sd_event_add_signal(). It takes the + event source object as the source parameter. - @@ -148,7 +147,7 @@ On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style error - code. + code. @@ -167,7 +166,6 @@ -EINVAL An invalid argument has been passed. - @@ -175,21 +173,18 @@ A handler is already installed for this signal or the signal was not blocked previously. - -ESTALE The event loop is already terminated. - -ECHILD The event loop has been created in a different process. - 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 CLOCK_REALTIME, CLOCK_MONOTONIC, CLOCK_BOOTTIME, - CLOCK_REALTIME_ALARM or + CLOCK_REALTIME_ALARM, or CLOCK_BOOTTIME_ALARM. See timerfd_create2 for details regarding the various types of clocks. The - usec 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 - accuracy 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 + usec 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 0), this timer source + "fires" immediately and is ready to be dispatched. The + accuracy parameter specifies an additional + accuracy value in µs specifying how much the timer event may be + delayed. Use 0 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 handler parameter shall reference a function to call when the timer elapses. The handler function will be passed the userdata 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 - prctl2) + prctl2), and additional scheduling latencies. To query the actual time the handler was called use sd_event_now3. @@ -167,22 +167,24 @@ sd_event_source_unref3, 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 - SD_EVENT_OFF with - sd_event_source_set_enabled3. + an event source does not fire anymore, even if it is still referenced, + disable the event source using + sd_event_source_set_enabled3 + with SD_EVENT_OFF. If the second parameter of - sd_event_add_time() 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. + sd_event_add_time() is + 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. If the handler to - sd_event_add_time() is passed as NULL, and - the event source fires, this will be considered a request to exit - the event loop. In this case, the userdata - parameter, cast to an integer is used for the exit code passed to + sd_event_add_time() is + NULL, and the event source fires, this will + be considered a request to exit the event loop. In this case, the + userdata parameter, cast to an integer, is + used for the exit code passed to sd_event_exit3. Use CLOCK_BOOTTIME_ALARM and @@ -192,7 +194,7 @@ In order to set up relative timers (that is, relative to the current time), retrieve the current time via sd_event_now3, - 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 usec parameter to sd_event_add_time(). @@ -212,30 +214,30 @@ latency will keep accumulating on the timer. sd_event_source_get_time() retrieves - the configured time value of a timer event source created + the configured time value of an event source created previously with sd_event_add_time(). 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. + time in, relative to the selected clock's epoch, in µs. sd_event_source_set_time() changes the - configured time value of a timer event source created previously - with sd_event_add_time(). It takes the event - source object and a time relative to the selected clock's - epoch, in µs. + time of an event source created previously with + sd_event_add_time(). It takes the event + source object and a time relative to the selected clock's epoch, + in µs. sd_event_source_get_time_accuracy() - retrieves the configured accuracy value of a timer event source + retrieves the configured accuracy value of a event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store - the accuracy in µs in. + the accuracy in. The accuracy is specified in µs. sd_event_source_set_time_accuracy() changes the configured accuracy of a timer event source created previously with sd_event_add_time(). It takes - the event source object and an accuracy, in µs. + the event source object and accuracy, in µs. sd_event_source_get_time_clock() - retrieves the configured clock of a timer event source created + retrieves the configured clock of a event source created previously with sd_event_add_time(). It takes the event source object and a pointer to a variable to store the clock identifier in. @@ -252,7 +254,7 @@ Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: 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 @@ Description - sd_event_now() returns the timestamp - the most recent event loop iteration began. This timestamp is - taken right after returning from the event sleep, and before + sd_event_now() 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 event - parameter takes the even loop object to retrieve the timestamp + parameter specifies the event loop object to retrieve the timestamp from. The clock parameter specifies the clock to retrieve the timestamp for, and is one of - CLOCK_REALTIME (or its equivalent + CLOCK_REALTIME (or equivalently CLOCK_REALTIME_ALARM), - CLOCK_MONOTONIC or - CLOCK_BOOTTIME (or its equivalent - CLOCK_BOOTTIME_ALARM), see clock_gettime2 + CLOCK_MONOTONIC, or + CLOCK_BOOTTIME (or equivalently + CLOCK_BOOTTIME_ALARM), see + clock_gettime2 for more information on the various clocks. The retrieved timestamp is stored in the usec 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 clock_gettime(). 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. + positive, and zero when the returned timestamp refers to an actual + event loop iteration. Return Value If the first event loop iteration has not run yet - sd_event_now() returns the requested - timestamp in usec and returns a positive, - non-zero return value. Otherwise, on success it will return the - iteration's timestamp in usec and 0 as - return value. On failure, the call returns a negative errno-style + sd_event_now() writes current time to + usec and returns a positive return value. + Otherwise, it will write the requested timestamp to usec + and return 0. On failure, the call returns a negative errno-style error code. Errors - Returned errors may indicate the following problems: + Returned values may indicate the following problems: