From patchwork Wed Dec 13 04:19:14 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: NeilBrown X-Patchwork-Id: 10109197 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 66CCD60352 for ; Wed, 13 Dec 2017 04:19:27 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 52EEF28C40 for ; Wed, 13 Dec 2017 04:19:27 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 442A728C6D; Wed, 13 Dec 2017 04:19:27 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AF92F28C40 for ; Wed, 13 Dec 2017 04:19:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751609AbdLMETZ (ORCPT ); Tue, 12 Dec 2017 23:19:25 -0500 Received: from mx2.suse.de ([195.135.220.15]:37789 "EHLO mx2.suse.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750749AbdLMETY (ORCPT ); Tue, 12 Dec 2017 23:19:24 -0500 X-Virus-Scanned: by amavisd-new at test-mx.suse.de Received: from relay2.suse.de (charybdis-ext.suse.de [195.135.220.254]) by mx2.suse.de (Postfix) with ESMTP id B2B54ACDD; Wed, 13 Dec 2017 04:19:22 +0000 (UTC) From: NeilBrown To: "Michael Kerrisk \(man-pages\)" Date: Wed, 13 Dec 2017 15:19:14 +1100 Cc: linux-man@vger.kernel.org, linux-nfs@vger.kernel.org, linux-fsdevel@vger.kernel.org Subject: [PATCH] fcntl.2, read.2, write.2: document "Lost locks" as cause for EIO. Message-ID: <87lgi7nttp.fsf@notabene.neil.brown.name> MIME-Version: 1.0 Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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 --- 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