diff --git a/Documentation/components/filesystem/index.rst b/Documentation/components/filesystem/index.rst index a2495cfcba6..798e85f8320 100644 --- a/Documentation/components/filesystem/index.rst +++ b/Documentation/components/filesystem/index.rst @@ -552,6 +552,7 @@ NuttX provides support for a variety of file systems out of the box. unionfs.rst userfs.rst zipfs.rst + inotify.rst FS Categories ------------- @@ -566,4 +567,4 @@ they require: binfs, procfs, userfs, hostfs, cromfs, unionfs, rpmsgfs, and zipfs. The requirements are specified by declaring the filesystem in the proper -array in ``fs/mount/fs_mount.c``. \ No newline at end of file +array in ``fs/mount/fs_mount.c``. diff --git a/Documentation/components/filesystem/inotify.rst b/Documentation/components/filesystem/inotify.rst new file mode 100644 index 00000000000..2fb37863b3f --- /dev/null +++ b/Documentation/components/filesystem/inotify.rst @@ -0,0 +1,133 @@ +======= +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 +------ +.. code-block:: c + + 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. + +.. c:function:: int inotify_init(void) + + Initializes a new inotify instance and returns a file descriptor + associated with a new inotify event queue. + +.. c:function:: 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. + +.. c:function:: 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. + +.. c:function:: 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: + +.. code-block:: c + + 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.