docs: filesystems: convert dnotify.txt to ReST

- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Add table markups;
- Add it to filesystems/index.rst

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Jan Kara <jack@suse.cz>
Link: https://lore.kernel.org/r/b39d6430d1c28438e833f01cb4597eff78703c75.1588021877.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/Documentation/filesystems/dnotify.rst b/Documentation/filesystems/dnotify.rst
new file mode 100644 (file)
index 0000000..a28a1f9
--- /dev/null
+++ b/Documentation/filesystems/dnotify.rst
@@ -0,0 +1,75 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================
+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
+-------
+See tools/testing/selftests/filesystems/dnotify_test.c for an example.
+
+NOTE
+----
+Beginning with Linux 2.6.13, dnotify has been replaced by inotify.
+See Documentation/filesystems/inotify.rst for more information on it.

diff --git a/Documentation/filesystems/dnotify.txt b/Documentation/filesystems/dnotify.txt
deleted file mode 100644 (file)
index 08d575e..0000000
--- a/Documentation/filesystems/dnotify.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-               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
--------
-See tools/testing/selftests/filesystems/dnotify_test.c for an example.
-
-NOTE
-----
-Beginning with Linux 2.6.13, dnotify has been replaced by inotify.
-See Documentation/filesystems/inotify.rst for more information on it.

diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 43717f11d10bd5aa7c6709d71b16b166cb79e32e..81510124111512eb82fcd0e31e511b61813bfea8 100644 (file)
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -25,6 +25,7 @@ algorithms work.
    locking
    directory-locking
    devpts
+   dnotify
 
    automount-support
 

diff --git a/MAINTAINERS b/MAINTAINERS
index 7d2fda93f8380e79b6976611828f3a5b2d540e46..46ba68a07a8f1a849e34fc278f89c15ee14c7faf 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4996,7 +4996,7 @@ M:        Jan Kara <jack@suse.cz>
 R:     Amir Goldstein <amir73il@gmail.com>
 L:     linux-fsdevel@vger.kernel.org
 S:     Maintained
-F:     Documentation/filesystems/dnotify.txt
+F:     Documentation/filesystems/dnotify.rst
 F:     fs/notify/dnotify/
 F:     include/linux/dnotify.h