4 files changed, 30 insertions, 11 deletions

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 43e89b1537d9..cc10ce7dc339 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -145,7 +145,7 @@ fb/
 feature-removal-schedule.txt
         - list of files and features that are going to be removed.
 filesystems/
-        - directory with info on the various filesystems that Linux supports.
+        - info on the vfs and the various filesystems that Linux supports.
 firmware_class/
         - request_firmware() hotplug interface info.
 floppy.txt
@@ -230,8 +230,6 @@ local_ops.txt
         - semantics and behavior of local atomic operations.
 lockdep-design.txt
         - documentation on the runtime locking correctness validator.
-locks.txt
-        - info on file locking implementations, flock() vs. fcntl(), etc.
 logo.gif
         - full colour GIF image of Linux logo (penguin - Tux).
 logo.txt
@@ -240,8 +238,6 @@ m68k/
         - directory with info about Linux on Motorola 68k architecture.
 magic-number.txt
         - list of magic numbers used to mark/protect kernel data structures.
-mandatory.txt
-        - info on the Linux implementation of Sys V mandatory file locking.
 mca.txt
         - info on supporting Micro Channel Architecture (e.g. PS/2) systems.
 md.txt
diff --git a/Documentation/filesystems/00-INDEX b/Documentation/filesystems/00-INDEX
index 59db1bca7027..599593a17067 100644
--- a/Documentation/filesystems/00-INDEX
+++ b/Documentation/filesystems/00-INDEX
@@ -52,6 +52,10 @@ isofs.txt
         - info and mount options for the ISO 9660 (CDROM) filesystem.
 jfs.txt
         - info and mount options for the JFS filesystem.
+locks.txt
+        - info on file locking implementations, flock() vs. fcntl(), etc.
+mandatory-locking.txt
+        - info on the Linux implementation of Sys V mandatory file locking.
 ncpfs.txt
         - info on Novell Netware(tm) filesystem using NCP protocol.
 ntfs.txt
diff --git a/Documentation/locks.txt b/Documentation/filesystems/locks.txt
index e3b402ef33bd..fab857accbd6 100644
--- a/Documentation/locks.txt
+++ b/Documentation/filesystems/locks.txt
@@ -53,11 +53,11 @@ fcntl(), with all the problems that implies.
 1.3 Mandatory Locking As A Mount Option
 ---------------------------------------
 
-Mandatory locking, as described in 'Documentation/mandatory.txt' was prior
-to this release a general configuration option that was valid for all
-mounted filesystems. This had a number of inherent dangers, not the least
-of which was the ability to freeze an NFS server by asking it to read a
-file for which a mandatory lock existed.
+Mandatory locking, as described in 'Documentation/filesystems/mandatory.txt'
+was prior to this release a general configuration option that was valid for
+all mounted filesystems.  This had a number of inherent dangers, not the
+least of which was the ability to freeze an NFS server by asking it to read
+a file for which a mandatory lock existed.
 
 From this release of the kernel, mandatory locking can be turned on and off
 on a per-filesystem basis, using the mount options 'mand' and 'nomand'.
diff --git a/Documentation/mandatory.txt b/Documentation/filesystems/mandatory-locking.txt
index bc449d49eee5..0979d1d2ca8b 100644
--- a/Documentation/mandatory.txt
+++ b/Documentation/filesystems/mandatory-locking.txt
@@ -3,7 +3,26 @@
                 Andy Walker <andy@lysaker.kvaerner.no>
 
                            15 April 1996
-
+                     (Updated September 2007)
+
+0. Why you should avoid mandatory locking
+-----------------------------------------
+
+The Linux implementation is prey to a number of difficult-to-fix race
+conditions which in practice make it not dependable:
+
+        - The write system call checks for a mandatory lock only once
+          at its start.  It is therefore possible for a lock request to
+          be granted after this check but before the data is modified.
+          A process may then see file data change even while a mandatory
+          lock was held.
+        - Similarly, an exclusive lock may be granted on a file after
+          the kernel has decided to proceed with a read, but before the
+          read has actually completed, and the reading process may see
+          the file data in a state which should not have been visible
+          to it.
+        - Similar races make the claimed mutual exclusion between lock
+          and mmap similarly unreliable.
 
 1. What is  mandatory locking?
 ------------------------------