[PATCH] fcntl.2, read.2, write.2: document "Lost locks" as cause for EIO.

NeilBrown
2017-12-13T04:19:14Z

[-- Attachment #1: Type: text/plain, Size: 2767 bytes --]

If an advisory lock is lost, then read/write requests on any
affected file descriptor can return EIO - for NFSv4 at least.

Signed-off-by: NeilBrown <neilb-IBi9RG/b67k@public.gmane.org>
---
man2/fcntl.2 | 24 ++++++++++++++++++++++++
man2/read.2 | 9 +++++++++
man2/write.2 | 9 +++++++++
3 files changed, 42 insertions(+)

diff --git a/man2/fcntl.2 b/man2/fcntl.2
index 67642384154c..6e6e26f66aa0 100644
--- a/man2/fcntl.2
+++ b/man2/fcntl.2
@@ -669,6 +669,30 @@ and
Mandatory locking is not specified by POSIX.
Some other systems also support mandatory locking,
although the details of how to enable it vary across systems.
+.SS Lost locks
+When an advisory lock is obtained on a networked filesystem such as
+NFS it is possible that the lock might get lost.
+This may happen due to administrative action on the server, or due to a
+network partition which lasts long enough for the server to assume
+that the client is no longer functioning.
+.PP
+When the filesystem determines that a lock has been lost, future
+.BR read (2)
+or
+.BR write (2)
+requests may fail with the error
+.BR EIO .
+This error will persist until the lock is removed or the file
+descriptor is closed.
+Since Linux 3.12,
+.\" commit ef1820f9be27b6ad158f433ab38002ab8131db4d
+this happens at least for NFSv4 including all minor versions.
+.PP
+Some versions of Unix send a signal
+.RB ( SIGLOST )
+in this circumstance.
+Linux does not define this signal, and does not provide any
+asynchronous notification of lost locks.
.SS Managing signals
.BR F_GETOWN ,
.BR F_SETOWN ,
diff --git a/man2/read.2 b/man2/read.2
index f2e1379865df..0fea86e523a5 100644
--- a/man2/read.2
+++ b/man2/read.2
@@ -163,6 +163,15 @@ or its process group
is orphaned.
It may also occur when there is a low-level I/O error
while reading from a disk or tape.
+A further possible cause of
+.B EIO
+on networked filesystems is when an advisory lock had been taken
+out on the file descriptor and this lock has been lost.
+See the
+.I "Lost locks"
+section of
+.BR fcntl (2)
+for further details.
.TP
.B EISDIR
.I fd
diff --git a/man2/write.2 b/man2/write.2
index 796cae8ba221..621a484dc3a2 100644
--- a/man2/write.2
+++ b/man2/write.2
@@ -197,6 +197,15 @@ be reported by a subsequent
(whether or not they were also reported by
.BR write (2)).
.\" commit 088737f44bbf6378745f5b57b035e57ee3dc4750
+An alternate cause of
+.B EIO
+on networked filesystems is when an advisory lock had been taken out
+on the file descriptor and this lock has been lost.
+See the
+.I "Lost locks"
+section of
+.BR fcntl (2)
+for further details.
.TP
.B ENOSPC
The device containing the file referred to by
--
2.14.0.rc0.dirty