[Gluster-devel] Report ESTALE as ENOENT

[J. Bruce Fields]

On Wed, Oct 18, 2017 at 10:19:13AM +0200, Michael Kerrisk (man-pages) wrote:
> On 10/11/2017 04:02 PM, J. Bruce Fields wrote:
> > On Wed, Oct 11, 2017 at 04:11:51PM +0530, Raghavendra G wrote:
> >> On Thu, Mar 31, 2016 at 1:22 AM, J. Bruce Fields <bfields at fieldses.org>
> >> wrote:
> >>
> >>> On Mon, Mar 28, 2016 at 04:21:00PM -0400, Vijay Bellur wrote:
> >>>> I would prefer to:
> >>>>
> >>>> 1. Return ENOENT for all system calls that operate on a path.
> >>>>
> >>>> 2. ESTALE might be ok for file descriptor based operations.
> >>>
> >>> Note that operations which operate on paths can fail with ESTALE when
> >>> they attempt to look up a component within a directory that no longer
> >>> exists.
> >>>
> >>
> >> But, "man 2 rmdir"  or "man 2 unlink" doesn't list ESTALE as a valid error.
> > 
> > In fact, almost no man pages list ESTALE as a valid error:
> > 
> > 	[bfields at patate man-pages]$ git grep ESTALE
> > 	Changes.old:        Change description for ESTALE
> > 	man2/open_by_handle_at.2:.B ESTALE
> > 	man2/open_by_handle_at.2:.B ESTALE
> > 	man3/errno.3:.B ESTALE
> > 
> > Cc'ing Michael Kerrisk for advice.  Is there some reason for that, or
> > can we fix those man pages?
> 
> Sure. I'd need help or a patch, to know which pages need fixing though.

The basic issue is that unlike on a local filesystem, NFS can't
necessarily keep an unlinked but in-use object around; so attempts to
use such may return ESTALE.

So, any call that could take a filehandle for an object on NFS could
return ESTALE.

Ditto for any call that might need to lookup within an NFS directory, if
the directory disappears during the lookup.

I say "NFS", but other distributed filesystems may have the same issue,
I don't know.

Example of how it might look for open/openat and read follows.

Alternatively we could stick something in BUGS or NOTES sections.  But
I like having an etry under ERRORS.  Maybe an entry under ERRORS that
just says "see NOTES"?

--b.

diff --git a/man2/read.2 b/man2/read.2
index f2e1379865df..b50602526901 100644
--- a/man2/read.2
+++ b/man2/read.2
@@ -164,6 +164,10 @@ is orphaned.
 It may also occur when there is a low-level I/O error
 while reading from a disk or tape.
 .TP
+.B ESTALE
+.I fd
+refers to a deleted object on a distributed filesystem such as NFS.
+.TP
 .B EISDIR
 .I fd
 refers to a directory.
diff --git a/man2/open.2 b/man2/open.2
index eeed37bfdd70..10f3f48ed625 100644
--- a/man2/open.2
+++ b/man2/open.2
@@ -1080,6 +1080,15 @@ but this kernel version does not provide the
 .B O_TMPFILE
 functionality.
 .TP
+.B ESTALE
+.I dirfd
+refers to a deleted directory on a distributed filesystem such as NFS.
+Or, a directory component in
+.I pathname
+is on a distributed filesystem such as NFS, and was removed during the
+process of traversing
+.IR pathname .
+.TP
 .B ENOMEM
 The named file is a FIFO,
 but memory for the FIFO buffer can't be allocated because