Inotify

Inotify is a kernel subsystem designed for monitoring filesystem events. It enables applications to monitor changes to files and directories in real-time, such as creation, deletion, modification, renaming, and more. inotify offers an efficient way to detect changes in the filesystem without the need for polling, thereby conserving system resources.

CONFIG

COFNIG_FS_NOTIFY=y

User Space API

All inotify user interfaces are declared in the file include/sys/inotify.h. And the usage is consistent with the Linux version.

int inotify_init(void)

Initializes a new inotify instance and returns a file descriptor associated with a new inotify event queue.

int inotify_init1(int flags)

inotify_init1 is an extended version of inotify_init, offering additional options for initializing an inotify instance. Unlike inotify_init, inotify_init1 allows you to specify certain flags to control the behavior of the inotify instance.

int inotify_add_watch(int fd, FAR const char *pathname, uint32_t mask)

Add a new watch, or modifies an existing watch, for the file whose location is specified in pathname; the caller must have read permission for this file. The fd argument is a file descriptor referring to the inotify instance whose watch list is to be modified. The events to be monitored for pathname are specified in the mask bit-mask argument.

int inotify_rm_watch(int fd, uint32_t wd)

Removes the watch associated with the watch descriptor wd from the inotify instance associated with the file descriptor fd.

Reading events from an inotify file descriptor

To determine what events have occurred, an application read from the inotify file descriptor. If no events have so far occurred, then, assuming a blocking file descriptor, read will block until at least one event occurs

Each successful read returns a buffer containing one or more of the following structures:

struct inotify_event {
  int      wd;       /* Watch descriptor */
  uint32_t mask;     /* Mask describing event */
  uint32_t cookie;   /* Unique cookie associating related
                       events (for rename(2)) */
  uint32_t len;      /* Size of name field */
  char     name[];   /* Optional null-terminated name */
};

wd identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to inotify_add_watch.

mask contains bits that describe the event that occurred

cookie is a unique integer that connects related events. Currently, this is used only for rename events, and allows the resulting pair of IN_MOVED_FROM and IN_MOVED_TO events to be connected by the application For all other event types, cookie is set to 0.

The name field is present only when an event is returned for a file inside a watched directory; it identifies the filename within the watched directory. This filename is null-terminated, and may include further null bytes (’0’) to align subsequent reads to a suitable address boundary.

The len field counts all of the bytes in name, including the null bytes; the length of each inotify_event structure is thus sizeof(struct inotify_event)+len.

inotify events

The inotify_add_watch mask argument and the mask field of the inotify_event structure returned when reading an inotify file descriptor are both bit masks identifying inotify events. The following bits can be specified in mask when calling inotify_add_watch and may be returned in the mask field returned by read.

IN_ACCESS :File was accessed

IN_MODIFY :File was modified

IN_ATTRIB :Metadata changed

IN_OPEN :File was opened

IN_MOVED_FROM :File was moved from X

IN_MOVED_TO :File was moved to Y

IN_CREATE :Subfile was created

IN_DELETE :Subfile was deleted

IN_DELETE_SELF :Self was deleted

IN_MOVE_SELF :Self was moved

Examples

Suppose an application is watching the directory dir and the file dir/myfile for all events. The examples below show some events that will be generated for these two objects.

fd = open(“dir/myfile”, O_RDWR);

Generates IN_OPEN events for both dir and dir/myfile.

read(fd, buf, count);

Generates IN_ACCESS events for both dir and dir/myfile.

write(fd, buf, count);

Generates IN_MODIFY events for both dir and dir/myfile.

fchmod(fd, mode);

Generates IN_ATTRIB events for both dir and dir/myfile.

NOTE

Inotify file descriptors can be monitored using select, poll, and epoll. When an event is available, the file descriptor indicates as readable.