Re: [PATCH] fsync.2: ERRORS: add EIO and ENOSPC

[Michael Kerrisk (man-pages)]

[CC += Neil, since he wrote the text we're talking about]

Hello Jan,

On 9/9/20 1:21 PM, Jan Kara wrote:
> On Wed 09-09-20 12:52:48, Michael Kerrisk (man-pages) wrote:
>>> So the error state isn't really stored "on pages in the file mapping".
>>> Current implementation (since 4.14) is that error state is stored in struct
>>> file (I think this tends to be called "file description" in manpages) and
>>
>> (Yes, "open file description" is the POSIX terminology for the thing that
>> sits between the FD and the inode--struct file in kernel parlance--and I
>> try to follow POSIX terminology in the manual pages where possible.
>>
>>> so EIO / ENOSPC is reported once for each file description of the file that
>>> was open before the error happened. Not sure if we want to be so precise in
>>> the manpages or if it just confuses people. 
>>
>> Well, people are confused now, so I think more detail would be good.
>>
>>> Anyway your takeway that no
>>> error on subsequent fsync() does not mean data was written is correct.
>>
>> Thanks. (See also my rply to Jeff.)
>>
>> By the way, a question related to your comments above. In the 
>> errors section, there is this:
>>
>>        EIO    An  error  occurred during synchronization.  This error may
>>               relate to data written to some other file descriptor on the
>> *             same  file.   Since Linux 4.13, errors from write-back will
>>               be reported to all file descriptors that might have written
>>               the  data  which  triggered  the  error.   Some filesystems
>>               (e.g., NFS) keep close track of  which  data  came  through
>>               which  file  descriptor,  and  give more precise reporting.
>>               Other  filesystems  (e.g.,  most  local  filesystems)  will
>>               report errors to all file descriptors that were open on the
>> *             file when the error was recorded.
>>
>> In the marked (*) lines, we have the word "file". Is this accurate? I mean, I
>> would normally take "file" in this context to mean the inode ('struct inode').
>> But I wonder if really what is meant here is "open file description"
>> ('struct file'). In other words, is the EIO being generated for all FDs 
>> connected to the same open file description, or for all FDs for all of the
>> open file descriptions connected to the inode? Your thoughts?
> 
> The error gets reported once for each "open file description" of the file
> (inode) where the error happened. If there are multiple file descriptors
> pointing to the same open file description, then only one of those file
> descriptors will see the error. This is inevitable consequence of kernel
> storing the error state in struct file and clearing it once it is
> reported...

So, the text in wrong two respects, I believe:

* It should be phrased in terms of "open file description", not "file",
in the lines that I marked.

* Where it says "to all file descriptors" (twice), it should rather say
"to any of the file descriptors [that refer to the open file description]"

Do you agree?

Thanks,

Michael

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