Various documentation improvements

See issue #389 for some related discussions.

diff --git a/include/fuse.h b/include/fuse.h
index 3e8aa2064450964990bf68695a4cc7623d063928..2d2291c06fc52e5bc864bf754ab5a11e6631f2d9 100644 (file)
--- a/include/fuse.h
+++ b/include/fuse.h
@@ -66,7 +66,7 @@ enum fuse_fill_dir_flags {
 
 /** Function to add an entry in a readdir() operation
  *
- * The *off* parameter can be any non-zero value that enableds the
+ * The *off* parameter can be any non-zero value that enables the
  * filesystem to identify the current point in the directory
  * stream. It does not need to be the actual physical position. A
  * value of zero is reserved to indicate that seeking in directories
@@ -220,7 +220,7 @@ struct fuse_config {
        /**
         * This option disables flushing the cache of the file
         * contents on every open(2).  This should only be enabled on
-        * filesystems, where the file data is never changed
+        * filesystems where the file data is never changed
         * externally (not through the mounted FUSE filesystem).  Thus
         * it is not suitable for network filesystems and other
         * intermediate filesystems.
@@ -394,12 +394,11 @@ struct fuse_operations {
         *  - Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be
         *    filtered out / handled by the kernel.
         *
-        *  - Access modes (O_RDONLY, O_WRONLY, O_RDWR) should be used
-        *    by the filesystem to check if the operation is
-        *    permitted.  If the ``-o default_permissions`` mount
-        *    option is given, this check is already done by the
-        *    kernel before calling open() and may thus be omitted by
-        *    the filesystem.
+        *  - Access modes (O_RDONLY, O_WRONLY, O_RDWR, O_EXEC, O_SEARCH)
+        *    should be used by the filesystem to check if the operation is
+        *    permitted.  If the ``-o default_permissions`` mount option is
+        *    given, this check is already done by the kernel before calling
+        *    open() and may thus be omitted by the filesystem.
         *
         *  - When writeback caching is enabled, the kernel may send
         *    read requests even for files opened with O_WRONLY. The
@@ -483,9 +482,9 @@ struct fuse_operations {
         *
         * 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, 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
+        * open file handle, 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
@@ -503,7 +502,7 @@ struct fuse_operations {
         * are unmapped.
         *
         * For every open() call there will be exactly one release() call
-        * with the same flags and file descriptor.      It is possible to
+        * with the same flags and file handle.  It is possible to
         * have a file opened more than once, in which case only the last
         * release will mean, that no more reads/writes will happen on the
         * file.  The return value of release is ignored.
@@ -794,7 +793,7 @@ struct fuse_context {
        /** Group ID of the calling process */
        gid_t gid;
 
-       /** Thread ID of the calling process */
+       /** Process ID of the calling thread */
        pid_t pid;
 
        /** Private filesystem data */

diff --git a/include/fuse_common.h b/include/fuse_common.h
index 83c9deefe4c798ed01ceffab0795db6a9f9f072c..5cf9feea9d764f53da3df3f2ffec0fd538feba2d 100644 (file)
--- a/include/fuse_common.h
+++ b/include/fuse_common.h
@@ -32,14 +32,24 @@ extern "C" {
 #endif
 
 /**
- * Information about open files
+ * Information about an open file.
+ *
+ * File Handles are created by the open, opendir, and create methods and closed
+ * by the release and releasedir methods.  Multiple file handles may be
+ * concurrently open for the same file.  Generally, a client will create one
+ * file handle per file descriptor, though in some cases multiple file
+ * descriptors can share a single file handle.
  */
 struct fuse_file_info {
        /** Open flags.  Available in open() and release() */
        int flags;
 
-       /** In case of a write operation indicates if this was caused by a
-           writepage */
+       /** In case of a write operation indicates if this was caused
+           by a delayed write from the page cache. If so, then the
+           context's pid, uid, and gid fields will not be valid, and
+           the *fh* value may not match the *fh* value that would
+           have been sent with the corresponding individual write
+           requests if write caching had been disabled. */
        unsigned int writepage : 1;
 
        /** Can be filled in by open, to use direct I/O on this file. */
@@ -67,8 +77,9 @@ struct fuse_file_info {
        /** Padding.  Do not use*/
        unsigned int padding : 27;
 
-       /** File handle.  May be filled in by filesystem in open().
-           Available in all other file operations */
+       /** File handle id.  May be filled in by filesystem in create,
+        * open, and opendir().  Available in most other file operations on the
+        * same file handle. */
        uint64_t fh;
 
        /** Lock owner id.  Available in locking operations and flush */