add inotify doc

Signed-off-by: guohao15 <guohao15@xiaomi.com>

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``.
+array in ``fs/mount/fs_mount.c``.

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.