.SH DESCRIPTION
This device is the primary interface between the FUSE filesystem driver
-and a userspace process wishing to provide the file system (referred to
+and a user-space process wishing to provide the filesystem (referred to
in the rest of this manual page as the
-.I file system daemon.
+.IR "filesystem daemon" ).
This manual page is intended for those
interested in understanding the kernel interface itself.
Those implementing a FUSE filesystem may wish to make use of
-a userspace library such as libfuse that abstracts away the low level
-interface.
+a user-space library such as
+.I libfuse
+that abstracts away the low-level interface.
At its core, FUSE is a simple client-server protocol, in which the Linux
kernel is the client and the daemon is the server.
-After obtaining a file descriptor to this device, the daemon may
+After obtaining a file descriptor for this device, the daemon may
.BR read (2)
requests from that file descriptor and is expected to
.BR write (2)
-back its replied.
-It is important to note, that a file descriptor is
-associated to a unique FUSE file system.
+back its replies.
+It is important to note that a file descriptor is
+associated with a unique FUSE filesystem.
In particular, opening a second copy of this device,
will not allow access to resources created
through the first file descriptor (and vice versa).
-
+.\"
.SS The basic protocol
Every message that is read by the daemon begins with a header described by
-the following struct:
+the following structure:
.in +4n
.nf
struct fuse_in_header {
- uint32_t len; /* Total length of the data, including this header */
- uint32_t opcode; /* The kind of operation (described below) */
- uint64_t unique; /* A unique identifier for this request */
- uint64_t nodeid; /* The id of the filesystem object being operated on */
- uint32_t uid; /* The uid of the requesting process */
- uint32_t gid; /* The gid of the requesting process */
- uint32_t pid; /* The pid of the requesting process */
- uint32_t padding;
+ uint32_t len; /* Total length of the data,
+ including this header */
+ uint32_t opcode; /* The kind of operation (see below) */
+ uint64_t unique; /* A unique identifier for this request */
+ uint64_t nodeid; /* ID of the filesystem object
+ being operated on */
+ uint32_t uid; /* UID of the requesting process */
+ uint32_t gid; /* GID of the requesting process */
+ uint32_t pid; /* PID of the requesting process */
+ uint32_t padding;
};
.fi
.in
-followed by a variable length data portion (which may be empty)
-specific to the requested operation
+The header is followed by a variable-length data portion
+(which may be empty) specific to the requested operation
(the requested operation is indicated by
-.I opcode
-).
+.IR opcode ).
The daemon should then process the request and if applicable send
-a reply (almost all operations require a reply - if they do not
+a reply (almost all operations require a reply; if they do not,
this is documented below), by performing a
-.BR write(2)
+.BR write (2)
to the file descriptor.
All replies must start with the following header:
.in +4n
.nf
- struct fuse_out_header {
- uint32_t len; /* Total length of data written to the fd */
- int32_t error; /* Any error that occurred (0 if none) */
- uint64_t unique; /* The value from the corresponding request */
- };
+struct fuse_out_header {
+ uint32_t len; /* Total length of data written to
+ the file descriptor */
+ int32_t error; /* Any error that occurred (0 if none) */
+ uint64_t unique; /* The value from the
+ corresponding request */
+};
.fi
.in
-again followed by (potentially empty) variable sized data depending on the
-executed request.
-However, if the reply is an error reply (i.e. error is set),
+This header is also followed by (potentially empty) variable-sized
+data depending on the executed request.
+However, if the reply is an error reply (i.e.,
+.I error
+is set),
then no further payload data should be sent, independent of the request.
-
+.\"
.SS Exchanged messages
-
This section should contain documentation for each of the messages
in the protocol.
This manual page is currently incomplete,
so not all messages are documented.
For each message, first the struct sent by the kernel is given,
followed by a description of the semantics of the message.
-
.TP
.BR FUSE_INIT " ( 25 )"
.in +4n
.nf
struct fuse_init_in {
- uint32_t major;
- uint32_t minor;
- uint32_t max_readahead; /* Since protocol v7.6 */
- uint32_t flags; /* Since protocol v7.6 */
+ uint32_t major;
+ uint32_t minor;
+ uint32_t max_readahead; /* Since protocol v7.6 */
+ uint32_t flags; /* Since protocol v7.6 */
};
.fi
.in
This is the first request sent by the kernel to the daemon.
-It is used to negotiate the protocol version and other file system parameters.
+It is used to negotiate the protocol version and other filesystem parameters.
Note that the protocol version may affect the layout of any structure
in the protocol (including this one).
The daemon must thus remember the negotiated version
and flags for each session.
As of the writing of this man page,
the highest supported kernel protocol version is
-.I 7.26.
+.IR 7.26 .
Users should be aware that the descriptions in this manual page
may be incomplete or incorrect for older or more recent protocol versions.
-The reply format for this request is
+The reply for this request has the following format:
+
.in +4n
.nf
struct fuse_init_out {
- uint32_t major;
- uint32_t minor;
- uint32_t max_readahead; /* Since v7.6 */
- /* field exists since v7.6 - certain flags were introduced
- in later versions */
- uint32_t flags;
- uint16_t max_background; /* Since v7.13 */
- uint16_t congestion_threshold; /* Since v7.13 */
- uint32_t max_write; /* Since v7.5 */
- uint32_t time_gran; /* Since v7.6 */
- uint32_t unused[9];
+ uint32_t major;
+ uint32_t minor;
+ uint32_t max_readahead; /* Since v7.6 */
+ uint32_t flags; /* Since v7.6; some flags bits
+ were introduced later */
+ uint16_t max_background; /* Since v7.13 */
+ uint16_t congestion_threshold; /* Since v7.13 */
+ uint32_t max_write; /* Since v7.5 */
+ uint32_t time_gran; /* Since v7.6 */
+ uint32_t unused[9];
};
.fi
.in
-If the major version supported by the kernel, is larger than that supported
+If the major version supported by the kernel is larger than that supported
by the daemon, the reply shall consist of only
.I uint32_t major
(following the usual header),
indicating the largest major version supported by the daemon.
The kernel will then issue a new
-.I FUSE_INIT
+.B FUSE_INIT
request conforming to the older version.
In the reverse case, the daemon should
quietly fall back to the kernel's major version.
The negotiated minor version is considered to be the minimum
of the minor versions provided by the daemon and the kernel and
both parties should use the protocol corresponding to said minor version.
-
.TP
.BR FUSE_GETATTR " ( 3 )"
.in +4n
.nf
struct fuse_getattr_in {
- uint32_t getattr_flags;
- uint32_t dummy;
- uint64_t fh; /* Only set if (getattr_flags & FUSE_GETATTR_FH)
+ uint32_t getattr_flags;
+ uint32_t dummy;
+ uint64_t fh; /* Set only if
+ (getattr_flags & FUSE_GETATTR_FH)
};
.fi
.in
As usual, the filesystem object operated on is indicated by
-.I header->nodeid.
+.IR header\->nodeid .
The daemon should compute the attributes
of this object and reply with the following message:
.in +4n
+
.nf
struct fuse_attr {
- uint64_t ino;
- uint64_t size;
- uint64_t blocks;
- uint64_t atime;
- uint64_t mtime;
- uint64_t ctime;
- uint32_t atimensec;
- uint32_t mtimensec;
- uint32_t ctimensec;
- uint32_t mode;
- uint32_t nlink;
- uint32_t uid;
- uint32_t gid;
- uint32_t rdev;
- uint32_t blksize;
- uint32_t padding;
+ uint64_t ino;
+ uint64_t size;
+ uint64_t blocks;
+ uint64_t atime;
+ uint64_t mtime;
+ uint64_t ctime;
+ uint32_t atimensec;
+ uint32_t mtimensec;
+ uint32_t ctimensec;
+ uint32_t mode;
+ uint32_t nlink;
+ uint32_t uid;
+ uint32_t gid;
+ uint32_t rdev;
+ uint32_t blksize;
+ uint32_t padding;
};
+
struct fuse_attr_out {
/* Attribute cache duration (seconds + nanoseconds) */
- uint64_t attr_valid;
- uint32_t attr_valid_nsec;
- uint32_t dummy;
+ uint64_t attr_valid;
+ uint32_t attr_valid_nsec;
+ uint32_t dummy;
struct fuse_attr attr;
};
.fi
.I struct fuse_attr
describe the attributes of the required file.
For the interpretation of these fields, see
-.BR stat(2)
-
+.BR stat (2).
.TP
.BR FUSE_ACCESS " ( 34 )"
.in +4n
.nf
struct fuse_access_in {
- uint32_t mask;
- uint32_t padding;
+ uint32_t mask;
+ uint32_t padding;
};
.fi
.in
No reply data is expected, but errors may be indicated
as usual in the reply header (in particular, access denied errors
may be indicated, by setting such field to
-.I -EACCES
-)
-
+.BR \-EACCES ).
.TP
.BR FUSE_OPEN " ( 14 ) and " FUSE_OPENDIR " ( 34 )"
.in +4n
.nf
struct fuse_open_in {
- uint32_t flags; /* The flags that were passed to the open(2) */
- uint32_t unused;
+ uint32_t flags; /* The flags that were passed
+ to the open(2) */
+ uint32_t unused;
};
.fi
.in
The requested operation is to open the node indicated by
-.I header->nodeid
-the exact semantics of what this means will depend on the
+.IR header\->nodeid .
+The exact semantics of what this means will depend on the
filesystem being implemented.
However, at the very least the
-file system should validate that the requested
+filesystem should validate that the requested
.I flags
-are valid for the indicated resource and then reply with
+are valid for the indicated resource and then send a reply with the
+following format:
.in +4n
.nf
struct fuse_open_out {
- uint64_t fh;
- uint32_t open_flags;
- uint32_t padding;
+ uint64_t fh;
+ uint32_t open_flags;
+ uint32_t padding;
};
.fi
.in
-where
+The
.I fh
-is an opaque identifier that the kernel will use to refer
-to this resource and open_flags is a bitfield of any number of
+field is an opaque identifier that the kernel will use to refer
+to this resource
+The
+.I open_flags
+field is a bit mask of any number of
.B FOPEN_*
flags, which indicate properties of this file handle to the kernel.
-
.TP
.BR FUSE_READ " ( 15 ) and " FUSE_READDIR " ( 28 )"
.in +4n
.nf
struct fuse_read_in {
- uint64_t fh;
- uint64_t offset;
- uint32_t size;
- uint32_t read_flags;
- uint64_t lock_owner;
- uint32_t flags;
- uint32_t padding;
+ uint64_t fh;
+ uint64_t offset;
+ uint32_t size;
+ uint32_t read_flags;
+ uint64_t lock_owner;
+ uint32_t flags;
+ uint32_t padding;
};
.fi
.in
-The requested action, it to read up to
+The requested action is to read up to
.I size
bytes of the file or directory, starting at
-.I offset
-the bytes should be returned directly following the out header,
+.IR offset .
+The bytes should be returned directly following the out header,
with no further special out structure.
-
.TP
.BR FUSE_INTERRUPT " ( 36 )"
.in +4n
.nf
struct fuse_interrupt_in {
- uint64_t unique;
+ uint64_t unique;
};
.fi
.in
The requested action is to cancel the pending operation indicated by
-.I unique
+.IR unique .
This request requires no response.
However, receipt of this message does
not by itself cancel the indicated operation.
-The kernel will still expect
-a reply to said operation (e.g. an EINTR error or a short read).
+The kernel will still expect a reply to said operation (e.g., an
+.I EINTR
+error or a short read).
At most one
.B FUSE_INTERRUPT
request will be issued for a given operation.
After issuing said operation,
-the kernel will wait uninterrutably for completion of the indicated request.
-
+the kernel will wait uninterruptibly for completion of the indicated request.
.TP
.BR FUSE_LOOKUP " ( 1 )"
-
Directly following the header is a filename to be looked up in the directory
indicated by
-.I header->nodeid.
-The expected reply is of the form
+.IR header\->nodeid .
+The expected reply is of the form:
.in +4n
.nf
struct fuse_entry_out {
- uint64_t nodeid; /* Inode ID */
- uint64_t generation; /* Inode generation: nodeid:gen must
- be unique for the fs's lifetime */
- uint64_t entry_valid;
- uint64_t attr_valid;
- uint32_t entry_valid_nsec;
- uint32_t attr_valid_nsec;
+ uint64_t nodeid; /* Inode ID */
+ uint64_t generation; /* Inode generation: nodeid:gen
+ must be unique for the
+ filesystem's lifetime */
+ uint64_t entry_valid;
+ uint64_t attr_valid;
+ uint32_t entry_valid_nsec;
+ uint32_t attr_valid_nsec;
struct fuse_attr attr;
};
.fi
The interpretation of timeouts and
.I attr
-is as in
-.B FUSE_GETATTR
-
+is as for
+.BR FUSE_GETATTR .
.TP
.BR FUSE_FLUSH " ( 36 )"
.in +4n
.nf
struct fuse_flush_in {
- uint64_t fh;
- uint32_t unused;
- uint32_t padding;
- uint64_t lock_owner;
+ uint64_t fh;
+ uint32_t unused;
+ uint32_t padding;
+ uint64_t lock_owner;
};
.fi
.in
No reply data is expected.
However, an empty reply message
still needs to be issued once the flush operation is complete.
-
.TP
.BR FUSE_RELEASE " ( 18 ) and " FUSE_RELEASEDIR " ( 29 )"
.in +4n
.nf
struct fuse_release_in {
- uint64_t fh;
- uint32_t flags;
- uint32_t release_flags;
- uint64_t lock_owner;
+ uint64_t fh;
+ uint32_t flags;
+ uint32_t release_flags;
+ uint64_t lock_owner;
};
.fi
.in
-The counter operation to
+These are the converse of
.BR FUSE_OPEN
-or
+and
.BR FUSE_OPENDIR
respectively.
The daemon may now free any resources associated with the
file handle
.I fh
as the kernel will no longer refer to it.
-There are no reply data associated with this request,
+There is no reply data associated with this request,
but a reply still needs to be issued once the request has
been completely processed.
-
.TP
.BR FUSE_STATFS " ( 17 )"
This operation implements
-.BR statfs(2)
-for this file system.
+.BR statfs (2)
+for this filesystem.
There is no input data associated with this request.
The expected reply data has the following structure:
+
.in +4n
.nf
struct fuse_kstatfs {
- uint64_t blocks;
- uint64_t bfree;
- uint64_t bavail;
- uint64_t files;
- uint64_t ffree;
- uint32_t bsize;
- uint32_t namelen;
- uint32_t frsize;
- uint32_t padding;
- uint32_t spare[6];
+ uint64_t blocks;
+ uint64_t bfree;
+ uint64_t bavail;
+ uint64_t files;
+ uint64_t ffree;
+ uint32_t bsize;
+ uint32_t namelen;
+ uint32_t frsize;
+ uint32_t padding;
+ uint32_t spare[6];
};
+
struct fuse_statfs_out {
struct fuse_kstatfs st;
};
.in
For the interpretation of these fields, see
-.BR statfs(2).
-
+.BR statfs (2).
.SH ERRORS
-
+.TP
.B EPERM
Returned from operations on a
.I /dev/fuse
-file descriptor that has not been mounted
-
+file descriptor that has not been mounted.
+.TP
.B EIO
Returned from
-.BR read(2)
+.BR read (2)
operations when the kernel's request is too large for the provided buffer.
.IR Note :
There are various ways in which incorrect use of these interfaces can cause
operations on the provided filesystem's files and directories to fail with
-.BR EIO.
-A partial list of such incorrect uses is changing
+.BR EIO .
+Among the possible incorrect uses are
+.IP * 3
+changing
.I mode & S_IFMT
-for an inode that has previous been reported to the kernel; or giving
-replies to the kernel that are shorter than what the kernel expected.
-
+for an inode that has previously been reported to the kernel; or
+.IP *
+giving replies to the kernel that are shorter than what the kernel expected.
+.TP
.B EINVAL
Returned from
-.BR write(2)
+.BR write (2)
if validation of the reply failed.
Note all mistakes in replies will be caught by this validation.
However, basic mistakes, such as short replies or an incorrect
.I unique
value.
-
+.TP
.B E2BIG
Returned from
-.BR read(2)
+.BR read (2)
operations when the kernel's request is too large for the provided buffer
-and the request was FUSE_SETXATTR.
-
+and the request was
+.BR FUSE_SETXATTR .
+.TP
.B ENODEV
-Returned from either operation if the FUSE file system was unmounted.
+Returned from either operation if the FUSE filesystem was unmounted.
projects / thirdparty / man-pages.git / commitdiff
