Improve documentation for the flush method (#378)

Fixes: #373

2 files changed, 26 insertions, 15 deletions

diff --git a/include/fuse.h b/include/fuse.h
index d3644ad..4f7131b 100644
--- 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 ae6736e..68fd521 100644
--- 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);