[Gluster-devel] Report ESTALE as ENOENT

[Michael Kerrisk (man-pages)]

Hi Bruce,

On 20 October 2017 at 22:22, J. Bruce Fields <bfields at fieldses.org> wrote:
> 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"?

I think having an entry in ERRORS is best. But, how many pages need
this fix? Quite a large number, I am guessing.

Cheers,

Michael


> 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



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/