Documentation: move dnotify.txt to filesystems/

I'm inclined to think dnotify belongs in filesystems/.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
Acked-by: Randy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

1 files changed, 99 insertions, 0 deletions

diff --git a/Documentation/filesystems/dnotify.txt b/Documentation/filesystems/dnotify.txt
new file mode 100644
index 000000000000..9f5d338ddbb8
--- /dev/null
+++ b/Documentation/filesystems/dnotify.txt
@@ -0,0 +1,99 @@
+                Linux Directory Notification
+                ============================
+
+           Stephen Rothwell <sfr@canb.auug.org.au>
+
+The intention of directory notification is to allow user applications
+to be notified when a directory, or any of the files in it, are changed.
+The basic mechanism involves the application registering for notification
+on a directory using a fcntl(2) call and the notifications themselves
+being delivered using signals.
+
+The application decides which "events" it wants to be notified about.
+The currently defined events are:
+
+        DN_ACCESS       A file in the directory was accessed (read)
+        DN_MODIFY       A file in the directory was modified (write,truncate)
+        DN_CREATE       A file was created in the directory
+        DN_DELETE       A file was unlinked from directory
+        DN_RENAME       A file in the directory was renamed
+        DN_ATTRIB       A file in the directory had its attributes
+                        changed (chmod,chown)
+
+Usually, the application must reregister after each notification, but
+if DN_MULTISHOT is or'ed with the event mask, then the registration will
+remain until explicitly removed (by registering for no events).
+
+By default, SIGIO will be delivered to the process and no other useful
+information.  However, if the F_SETSIG fcntl(2) call is used to let the
+kernel know which signal to deliver, a siginfo structure will be passed to
+the signal handler and the si_fd member of that structure will contain the
+file descriptor associated with the directory in which the event occurred.
+
+Preferably the application will choose one of the real time signals
+(SIGRTMIN + <n>) so that the notifications may be queued.  This is
+especially important if DN_MULTISHOT is specified.  Note that SIGRTMIN
+is often blocked, so it is better to use (at least) SIGRTMIN + 1.
+
+Implementation expectations (features and bugs :-))
+---------------------------
+
+The notification should work for any local access to files even if the
+actual file system is on a remote server.  This implies that remote
+access to files served by local user mode servers should be notified.
+Also, remote accesses to files served by a local kernel NFS server should
+be notified.
+
+In order to make the impact on the file system code as small as possible,
+the problem of hard links to files has been ignored.  So if a file (x)
+exists in two directories (a and b) then a change to the file using the
+name "a/x" should be notified to a program expecting notifications on
+directory "a", but will not be notified to one expecting notifications on
+directory "b".
+
+Also, files that are unlinked, will still cause notifications in the
+last directory that they were linked to.
+
+Configuration
+-------------
+
+Dnotify is controlled via the CONFIG_DNOTIFY configuration option.  When
+disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
+
+Example
+-------
+
+        #define _GNU_SOURCE     /* needed to get the defines */
+        #include <fcntl.h>      /* in glibc 2.2 this has the needed
+                                           values defined */
+        #include <signal.h>
+        #include <stdio.h>
+        #include <unistd.h>
+
+        static volatile int event_fd;
+
+        static void handler(int sig, siginfo_t *si, void *data)
+        {
+                event_fd = si->si_fd;
+        }
+
+        int main(void)
+        {
+                struct sigaction act;
+                int fd;
+
+                act.sa_sigaction = handler;
+                sigemptyset(&act.sa_mask);
+                act.sa_flags = SA_SIGINFO;
+                sigaction(SIGRTMIN + 1, &act, NULL);
+
+                fd = open(".", O_RDONLY);
+                fcntl(fd, F_SETSIG, SIGRTMIN + 1);
+                fcntl(fd, F_NOTIFY, DN_MODIFY|DN_CREATE|DN_MULTISHOT);
+                /* we will now be notified if any of the files
+                   in "." is modified or new files are created */
+                while (1) {
+                        pause();
+                        printf("Got event on fd=%d\n", event_fd);
+                }
+        }