From 1a6c9811e56bb2d113746325c8cdacb936fa895e Mon Sep 17 00:00:00 2001 From: Alan Somers Date: Thu, 4 Apr 2019 11:04:57 -0600 Subject: [PATCH] Various documentation improvements See issue #389 for some related discussions. --- include/fuse.h | 25 ++++++++++++------------- include/fuse_common.h | 21 ++++++++++++++++----- 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/include/fuse.h b/include/fuse.h index 3e8aa20..2d2291c 100644 --- 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 83c9dee..5cf9fee 100644 --- 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 */ -- 2.30.2