From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_event_add_inotify.xml | 234 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 man/sd_event_add_inotify.xml (limited to 'man/sd_event_add_inotify.xml') diff --git a/man/sd_event_add_inotify.xml b/man/sd_event_add_inotify.xml new file mode 100644 index 0000000..c7af7bd --- /dev/null +++ b/man/sd_event_add_inotify.xml @@ -0,0 +1,234 @@ + + + + + + + + sd_event_add_inotify + systemd + + + + sd_event_add_inotify + 3 + + + + sd_event_add_inotify + sd_event_add_inotify_fd + sd_event_source_get_inotify_mask + sd_event_inotify_handler_t + + Add an "inotify" file system inode event source to an event loop + + + + + #include <systemd/sd-event.h> + + typedef struct sd_event_source sd_event_source; + + + typedef int (*sd_event_inotify_handler_t) + sd_event_source *s + const struct inotify_event *event + void *userdata + + + + int sd_event_add_inotify + sd_event *event + sd_event_source **source + const char *path + uint32_t mask + sd_event_inotify_handler_t handler + void *userdata + + + + int sd_event_add_inotify_fd + sd_event *event + sd_event_source **source + int fd + uint32_t mask + sd_event_inotify_handler_t handler + void *userdata + + + + int sd_event_source_get_inotify_mask + sd_event_source *source + uint32_t *mask + + + + + + + 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 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. + + + 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. + + As a special limitation the priority of inotify event sources may only be altered (see + sd_event_source_set_priority3) + in the time between creation of the event source object with sd_event_add_inotify() and the + beginning of the next event loop iteration. Attempts of changing the priority any later will be refused. Consider + freeing and allocating a new inotify event source to change the priority at that point. + + To destroy an event source object use + 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 disabling + it with + sd_event_source_set_enabled3. + + If the second parameter of sd_event_add_inotify() 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. + + If the handler parameter to sd_event_add_inotify() 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 passed as + the exit code parameter to + sd_event_exit3. + + sd_event_source_get_inotify_mask() retrieves the configured inotify watch mask of an + event source created previously with sd_event_add_inotify(). It takes the event source object + as the source parameter and a pointer to a uint32_t variable to return the mask + in. + + + + Return Value + + On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style + error code. + + + Errors + + Returned errors may indicate the following problems: + + + + -ENOMEM + + Not enough memory to allocate an object. + + + + -EINVAL + + An invalid argument has been passed. This includes specifying a mask with + IN_MASK_ADD set. + + + + -ESTALE + + The event loop is already terminated. + + + + + -ECHILD + + The event loop has been created in a different process. + + + + + -EDOM + + The passed event source is not an inotify process event source. + + + + -EBADF + + The passed file descriptor is not valid. + + + + -ENOSYS + + sd_event_add_inotify_fd() was called without + /proc/ mounted. + + + + + + + + Examples + + + A simple program that uses inotify to monitor one or two directories + + + + + + + + + See Also + + + systemd1, + sd-event3, + sd_event_new3, + sd_event_now3, + sd_event_add_io3, + sd_event_add_time3, + sd_event_add_signal3, + sd_event_add_defer3, + sd_event_add_child3, + sd_event_source_set_enabled3, + sd_event_source_set_priority3, + sd_event_source_set_userdata3, + sd_event_source_set_description3, + sd_event_source_set_floating3, + waitid2 + + + + -- cgit v1.2.3