From: Zbigniew Jędrzejewski-Szmek Date: Wed, 5 Jan 2022 13:00:59 +0000 (+0100) Subject: man: add better descriptions of what event handlers do X-Git-Tag: v251-rc1~585^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9809a788e409278a8225b1542813f2e6c5765ef8;p=thirdparty%2Fsystemd.git man: add better descriptions of what event handlers do The meaning of the return value, the default handlers, and loop exiting are now described. --- diff --git a/man/sd_event_add_child.xml b/man/sd_event_add_child.xml index 2961b3ee5e3..621efad8d3f 100644 --- a/man/sd_event_add_child.xml +++ b/man/sd_event_add_child.xml @@ -114,25 +114,29 @@ event loop. The event loop object is specified in the event parameter, the event source object is returned in the source parameter. The pid parameter specifies the PID of the process to watch, which must be a direct child process of the invoking - process. The handler must reference a function to call when the process changes - state. The handler function will be passed the userdata pointer, which may be - chosen freely by the caller. The handler also receives a pointer to a siginfo_t - structure containing information about the child process event. The options - parameter determines which state changes will be watched for. It must contain an OR-ed mask of - WEXITED (watch for the child process terminating), WSTOPPED - (watch for the child process being stopped by a signal), and WCONTINUED (watch for - the child process being resumed by a signal). See waitid2 for - further information. - - Only a single handler may be installed for a specific - child process. The handler is enabled for a single event - (SD_EVENT_ONESHOT), but this may be changed - with + process. The options parameter determines which state changes will be watched for. + It must contain an OR-ed mask of WEXITED (watch for the child process terminating), + WSTOPPED (watch for the child process being stopped by a signal), and + WCONTINUED (watch for the child process being resumed by a signal). See + waitid2 + for further information. + + The handler must be a function to call when the process changes state or + NULL. The handler function will be passed the userdata + pointer, which may be chosen freely by the caller. The handler also receives a pointer to a + siginfo_t structure containing information about the child process event. The + handler may return negative to signal an error (see below), other return values are ignored. If + handler is NULL, a default handler that calls + sd_event_exit3 will be + used. + + Only a single handler may be installed for a specific child process. The handler is enabled for a + single event (SD_EVENT_ONESHOT), 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. + If the handler function returns a negative error code, it will either be disabled after the invocation, + even if the SD_EVENT_ON mode was requested before, or it will cause the loop to + terminate, see + sd_event_source_set_exit_on_failure3. To destroy an event source object use diff --git a/man/sd_event_add_defer.xml b/man/sd_event_add_defer.xml index 54e8823000e..e56e16a0328 100644 --- a/man/sd_event_add_defer.xml +++ b/man/sd_event_add_defer.xml @@ -66,14 +66,17 @@ Description - These three functions add new static event sources to an - event loop. The event loop object is specified in the - event parameter, the event source object is - returned in the source parameter. The event - sources are enabled statically and will "fire" when the event loop - is run and the conditions described below are met. The handler - function will be passed the userdata - pointer, which may be chosen freely by the caller. + These three functions add new static event sources to an event loop. The event loop object is + specified in the event parameter, the event source object is returned in the + source parameter. The event sources are enabled statically and will "fire" when + the event loop is run and the conditions described below are met. + + The handler is a function to call or NULL. The handler + function will be passed the userdata pointer, which may be chosen freely by the + caller. The handler may return negative to signal an error (see below), other return values are + ignored. If handler is NULL, a default handler that calls + sd_event_exit3 will be + used. sd_event_add_defer() adds a new event source that will be dispatched instantly, before the event loop @@ -103,9 +106,11 @@ (SD_EVENT_ON) or to make it fire just once (SD_EVENT_ONESHOT). - 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. + If the handler function returns a negative error code, it will either be disabled after the + invocation, even if the SD_EVENT_ON mode was requested before, or it will cause the + loop to terminate, see + sd_event_source_set_exit_on_failure3. + To destroy an event source object use sd_event_source_unref3, diff --git a/man/sd_event_add_inotify.xml b/man/sd_event_add_inotify.xml index d632bf7282e..e97fda25d7c 100644 --- a/man/sd_event_add_inotify.xml +++ b/man/sd_event_add_inotify.xml @@ -70,33 +70,40 @@ Description sd_event_add_inotify() adds a new inotify7 file system inode - event source to an event loop. The event loop object is specified in the event parameter, - the event source object is returned in the source parameter. The path - parameter specifies the path of the file system inode to watch. The handler must reference a - function to call when the inode changes. The handler function will be passed the userdata - pointer, which may be chosen freely by the caller. The handler also receives a pointer to a struct - inotify_event structure containing information about the inode event. The mask - parameter specifies which types of inode events to watch specifically. It must contain an OR-ed combination of - IN_ACCESS, IN_ATTRIB, IN_CLOSE_WRITE, … flags. See - inotify7 for + project='man-pages'>inotify7 file + system inode event source to an event loop. The event loop object is specified in the + event parameter, the event source object is returned in the + source parameter. The path parameter specifies the path of + the file system inode to watch. The mask parameter specifies which types of inode + events to watch specifically. It must contain an OR-ed combination of IN_ACCESS, + IN_ATTRIB, IN_CLOSE_WRITE, … flags. See inotify7 for further information. + The handler must reference a function to call when the inode changes or + NULL. The handler function will be passed the userdata pointer, + which may be chosen freely by the caller. The handler also receives a pointer to a struct + inotify_event structure containing information about the inode event. The handler may return + negative to signal an error (see below), other return values are ignored. If + handler is NULL, a default handler that calls + sd_event_exit3 will be + used. + sd_event_add_inotify_fd() is identical to sd_event_add_inotify(), except that it takes a file descriptor to an inode (possibly - an O_PATH one, but any other will do too) instead of a path in the file - system. + an O_PATH one, but any other will do too) instead of a path in the file system. + If multiple event sources are installed for the same inode the backing inotify watch descriptor is automatically shared. The mask parameter may contain any flag defined by the inotify API, with the exception of IN_MASK_ADD. The handler is enabled continuously (SD_EVENT_ON), but this may be changed with - sd_event_source_set_enabled3. Alternatively, - the IN_ONESHOT mask flag may be used to request SD_EVENT_ONESHOT mode. - 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. - + sd_event_source_set_enabled3. + Alternatively, the IN_ONESHOT mask flag may be used to request + SD_EVENT_ONESHOT mode. 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. As a special limitation the priority of inotify event sources may only be altered (see sd_event_source_set_priority3) diff --git a/man/sd_event_add_io.xml b/man/sd_event_add_io.xml index 323e57c79d0..383a58a074e 100644 --- a/man/sd_event_add_io.xml +++ b/man/sd_event_add_io.xml @@ -115,27 +115,27 @@ EPOLLRDHUP, EPOLLPRI, and EPOLLET, see epoll_ctl2 - for details. The handler shall reference a - 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, an event source will stay enabled - continuously (SD_EVENT_ON), but this may be - changed with + for details. + + The handler is a function to call when the event source is triggered or + NULL. 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. The + handler may return negative to signal an error (see below), other return values are ignored. If + handler is NULL, a default handler that calls + sd_event_exit3 will be + used. + + 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 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. - + If the handler function returns a negative error code, it will either be disabled after the invocation, + even if the SD_EVENT_ON mode was requested before, or it will cause the loop to + terminate, see + sd_event_source_set_exit_on_failure3. + Note 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 that the event source won't be triggered anymore, as diff --git a/man/sd_event_add_signal.xml b/man/sd_event_add_signal.xml index 1f0854f6cb0..b2aaff87c10 100644 --- a/man/sd_event_add_signal.xml +++ b/man/sd_event_add_signal.xml @@ -64,16 +64,18 @@ source parameter. The signal parameter specifies the numeric signal to be handled (see signal7). - The handler parameter must reference a - function to call when the signal is received or be - NULL. The handler function will be passed - the userdata pointer, which may be chosen - freely by the caller. The handler also receives a pointer to a - signalfd_siginfo structure containing - information about the received signal. See signalfd2 - for further information. + project='man-pages'>signal7). + + The handler parameter is a function to call when the signal is received or + NULL. The handler function will be passed the userdata + pointer, which may be chosen freely by the caller. The handler also receives a pointer to a + signalfd_siginfo structure containing information about the received signal. See + signalfd2 + for further information. The handler may return negative to signal an error (see below), other return + values are ignored. If handler is NULL, a default handler + that calls + sd_event_exit3 will be + used. Only a single handler may be installed for a specific signal. The signal must be blocked in all threads before this function is called (using By default, the event source is enabled permanently (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. + If the handler function returns a negative error code, it will either be disabled after the + invocation, even if the SD_EVENT_ON mode was requested before, or it will cause the + loop to terminate, see + sd_event_source_set_exit_on_failure3. To destroy an event source object use diff --git a/man/sd_event_add_time.xml b/man/sd_event_add_time.xml index 3e8927f9666..19f112b0f60 100644 --- a/man/sd_event_add_time.xml +++ b/man/sd_event_add_time.xml @@ -122,25 +122,30 @@ 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, - 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 trigger time, even if it is actually called - slightly later, subject to the specified accuracy value, the kernel timer slack (see - prctl2), and additional - scheduling latencies. To query the actual time the handler was called use - sd_event_now3. - - By default, the timer will elapse once - (SD_EVENT_ONESHOT), but this may be changed - with + improving power efficiency. + + The handler is a function to call when the timer elapses or + NULL. The userdata pointer will be passed to the handler + function, and may be chosen freely by the caller. The configured trigger time is also passed to the + handler, even if the call actually happens slightly later, subject to the specified accuracy value, the + kernel timer slack (see + prctl2), and + additional scheduling latencies. To query the actual time the handler was called use + sd_event_now3. The + handler may return negative to signal an error (see below), other return values are ignored. If + handler is NULL, a default handler that calls + sd_event_exit3 will be + used. + + By default, the timer will elapse once (SD_EVENT_ONESHOT), 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 a timer event set to SD_EVENT_ON will - fire continuously unless its configured time is updated using - sd_event_source_set_time(). - + If the handler function returns a negative error code, it will either be disabled after the invocation, + even if the SD_EVENT_ON mode was requested before, or it will cause the loop to + terminate, see + sd_event_source_set_exit_on_failure3. + Note that a timer event set to SD_EVENT_ON will fire continuously unless its + configured time is updated using sd_event_source_set_time(). sd_event_add_time_relative() is like sd_event_add_time(), but takes a relative time specification. It's relative to the current time of the event loop iteration,