Re: EINTR for fsync(2)

Re: EINTR for fsync(2)

[Alejandro Colomar (man-pages)]

Hello Alexander,

On 1/31/22 19:32, Mathnerd314 wrote:
> Hi,
> 
> The POSIX standard says fsync(2) can return EINTR:
> https://pubs.opengroup.org/onlinepubs/9699919799/
> 
> The man page does not:
> https://man7.org/linux/man-pages/man2/fsync.2.html
> 
> I think fsync can be interrupted by a signal on Linux, so this should
> just be an oversight in the man page.
> 
> At least, fsync on fuse seems be able to return EINTR:
> https://github.com/torvalds/linux/blob/5367cf1c3ad02f7f14d79733814302a96cc97b96/fs/fuse/dev.c#L114
> 
> Actually there seem to be numerous error codes that can be returned
> from all filesystem calls on fuse: ENOTCONN, ENOMEM, etc. But EINTR is
> at least documented in the POSIX standard, whereas these others seem
> really rare. But for full correctness I suppose these should be
> documented as well. It would be quite an undertaking.
> 
> -- Mathnerd314 (pseudonym)

I got this report on linux-man@.  Could you please confirm if there are
any ERRORS that should be added to the fsync(2) manual page?

Thanks,

Alex

Mathnerd314:  Thanks for the report!  It's useful to CC the relevant
kernel developers when reporting non-trivial bugs such as this one.
They know better than we do.  :)

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: EINTR for fsync(2)

[Matthew Wilcox]

On Mon, Jan 31, 2022 at 09:44:38PM +0100, Alejandro Colomar (man-pages) wrote:
> Hello Alexander,
> 
> On 1/31/22 19:32, Mathnerd314 wrote:
> > Hi,
> > 
> > The POSIX standard says fsync(2) can return EINTR:
> > https://pubs.opengroup.org/onlinepubs/9699919799/
> > 
> > The man page does not:
> > https://man7.org/linux/man-pages/man2/fsync.2.html
> > 
> > I think fsync can be interrupted by a signal on Linux, so this should
> > just be an oversight in the man page.
> > 
> > At least, fsync on fuse seems be able to return EINTR:
> > https://github.com/torvalds/linux/blob/5367cf1c3ad02f7f14d79733814302a96cc97b96/fs/fuse/dev.c#L114
> > 
> > Actually there seem to be numerous error codes that can be returned
> > from all filesystem calls on fuse: ENOTCONN, ENOMEM, etc. But EINTR is
> > at least documented in the POSIX standard, whereas these others seem
> > really rare. But for full correctness I suppose these should be
> > documented as well. It would be quite an undertaking.

It's probably worth reading this part of POSIX:

: 2.3 Error Numbers
:
: Most functions can provide an error number. The means by which each
: function provides its error numbers is specified in its description.
: 
: Some functions provide the error number in a variable accessed through
: the symbol errno, defined by including the <errno.h> header. The value
: of errno should only be examined when it is indicated to be valid by
: a function's return value. No function in this volume of POSIX.1-2017
: shall set errno to zero. For each thread of a process, the value of
: errno shall not be affected by function calls or assignments to errno
: by other threads.
: 
: Some functions return an error number directly as the function
: value. These functions return a value of zero to indicate success.
: 
: If more than one error occurs in processing a function call, any one
: of the possible errors may be returned, as the order of detection is
: undefined.
: 
: Implementations may support additional errors not included in this list,
: may generate errors included in this list under circumstances other
: than those described here, or may contain extensions or limitations that
: prevent some errors from occurring.
: 
: The ERRORS section on each reference page specifies which error conditions
: shall be detected by all implementations (``shall fail") and which may
: be optionally detected by an implementation (``may fail"). If no error
: condition is detected, the action requested shall be successful. If an
: error condition is detected, the action requested may have been partially
: performed, unless otherwise stated.

So while it's worth adding EINTR to the man page, I don't think it's
worth going through an exercise of trying to add every possible
errno to every syscall.

Re: EINTR for fsync(2)

[Alejandro Colomar (man-pages)]

Hi Mathnerd314, Matthew,

On 2/1/22 01:30, Matthew Wilcox wrote:
[...]
> So while it's worth adding EINTR to the man page, I don't think it's
> worth going through an exercise of trying to add every possible
> errno to every syscall.
> 

Okay.  I documented this error.

Thanks,

Alex

---
    fsync.2: ERRORS: Document EINTR

    Reported-by: Mathnerd314 <mathnerd314.gph@gmail.com>
    Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
    Cc: <linux-fsdevel@vger.kernel.org>
    Cc: Matthew Wilcox <willy@infradead.org>
    Cc: Alexander Viro <viro@zeniv.linux.org.uk>


diff --git a/man2/fsync.2 b/man2/fsync.2
index 0f070ed2c..c79723ed8 100644
--- a/man2/fsync.2
+++ b/man2/fsync.2
@@ -126,6 +126,10 @@ is set to indicate the error.
 .I fd
 is not a valid open file descriptor.
 .TP
+.B EINTR
+The function was interrupted by a signal; see
+.BR signal (7).
+.TP
 .B EIO
 An error occurred during synchronization.
 This error may relate to data written to some other file descriptor


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/