Improve documentation for the flush method (#378)

Fixes: #373

diff --git a/include/fuse.h b/include/fuse.h
index d3644ad51ac00b6038db4cbf8708384306b0f668..4f7131b6f4f690e2e176d8fcdde5593f60bae785 100644 (file)
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -471,21 +471,28 @@ struct fuse_operations {
         * BIG NOTE: This is not equivalent to fsync().  It's not a
         * request to sync dirty data.
         *
-        * Flush is called on each close() of a file descriptor.  So if a
-        * filesystem wants to return write errors in close() and the file
-        * has cached dirty data, this is a good place to write back data
-        * and return any errors.  Since many applications ignore close()
-        * errors this is not always useful.
+        * Flush is called on each close() of a file descriptor, as opposed to
+        * release which is called on the close of the last file descriptor for
+        * a file.  Under Linux, errors returned by flush() will be passed to 
+        * userspace as errors from close(), so flush() is a good place to write
+        * back any cached dirty data. However, many applications ignore errors 
+        * on close(), and on non-Linux systems, close() may succeed even if flush()
+        * returns an error. For these reasons, filesystems should not assume
+        * that errors returned by flush will ever be noticed or even
+        * delivered.
         *
         * NOTE: The flush() method may be called more than once for each
-        * open().      This happens if more than one file descriptor refers
-        * to an opened file due to dup(), dup2() or fork() calls.      It is
-        * not possible to determine if a flush is final, so each flush
-        * should be treated equally.  Multiple write-flush sequences are
-        * relatively rare, so this shouldn't be a problem.
-        *
-        * Filesystems shouldn't assume that flush will always be called
-        * after some writes, or that if will be called at all.
+        * open().  This happens if more than one file descriptor refers to an
+        * opened file, e.g. due to dup(), dup2() or fork() calls.  It is not
+        * possible to determine if a flush is final, so each flush should be
+        * treated equally.  Multiple write-flush sequences are relatively
+        * rare, so this shouldn't be a problem.
+        *
+        * Filesystems shouldn't assume that flush will be called at any
+        * particular point.  It may be called more times than expected, or not
+        * at all.
+        *
+        * [close]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html
         */
        int (*flush) (const char *, struct fuse_file_info *);
 

diff --git a/include/fuse_lowlevel.h b/include/fuse_lowlevel.h
index ae6736eb66b8451dd2c4c87e0fcc99a6de8133b8..68fd521fe850fe01bbba72fcab6f7fcdb4af5801 100644 (file)
--- a/include/fuse_lowlevel.h
+++ b/include/fuse_lowlevel.h
@@ -583,8 +583,10 @@ struct fuse_lowlevel_ops {
         *
         * NOTE: the name of the method is misleading, since (unlike
         * fsync) the filesystem is not forced to flush pending writes.
-        * One reason to flush data, is if the filesystem wants to return
-        * write errors.
+        * One reason to flush data is if the filesystem wants to return
+        * write errors during close.  However, such use is non-portable
+        * because POSIX does not require [close] to wait for delayed I/O to
+        * complete.
         *
         * If the filesystem supports file locking operations (setlk,
         * getlk) it should remove all locks belonging to 'fi->owner'.
@@ -600,6 +602,8 @@ struct fuse_lowlevel_ops {
         * @param req request handle
         * @param ino the inode number
         * @param fi file information
+        *
+        * [close]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/close.html
         */
        void (*flush) (fuse_req_t req, fuse_ino_t ino,
                       struct fuse_file_info *fi);