]> git.ipfire.org Git - thirdparty/man-pages.git/blobdiff - man4/fuse.4
inotify.7: Add missing #include in example program
[thirdparty/man-pages.git] / man4 / fuse.4
index 786efc0268a49e48236712e257f89e701fe27e02..87da0084902e1b8ba1b566a1118f37858a0dd07b 100644 (file)
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH FUSE 4 2016-12-10 "Linux" "Linux Programmer's Manual"
+.TH FUSE 4 2018-02-02 "Linux" "Linux Programmer's Manual"
 .SH NAME
-/dev/fuse \- Filesystem in Userspace (FUSE) device
+fuse \- Filesystem in Userspace (FUSE) device
 .SH SYNOPSIS
 .nf
 .B #include <linux/fuse.h>
-.nf
+.fi
 .SH DESCRIPTION
-
+.PP
 This device is the primary interface between the FUSE filesystem driver
 and a user-space process wishing to provide the filesystem (referred to
 in the rest of this manual page as the
@@ -42,7 +42,7 @@ Those implementing a FUSE filesystem may wish to make use of
 a user-space library such as
 .I libfuse
 that abstracts away the low-level interface.
-
+.PP
 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 for this device, the daemon may
@@ -59,9 +59,9 @@ 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 structure:
-
+.PP
 .in +4n
-.nf
+.EX
 struct fuse_in_header {
     uint32_t len;       /* Total length of the data,
                            including this header */
@@ -74,23 +74,23 @@ struct fuse_in_header {
     uint32_t pid;       /* PID of the requesting process */
     uint32_t padding;
 };
-.fi
+.EE
 .in
-
+.PP
 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
 .IR opcode ).
-
+.PP
 The daemon should then process the request and if applicable send
 a reply (almost all operations require a reply; if they do not,
 this is documented below), by performing a
 .BR write (2)
 to the file descriptor.
 All replies must start with the following header:
-
+.PP
 .in +4n
-.nf
+.EX
 struct fuse_out_header {
     uint32_t len;       /* Total length of data written to
                            the file descriptor */
@@ -98,9 +98,9 @@ struct fuse_out_header {
     uint64_t unique;    /* The value from the
                            corresponding request */
 };
-.fi
+.EE
 .in
-
+.PP
 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.,
@@ -117,18 +117,18 @@ 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
-
+.IP
 .in +4n
-.nf
+.EX
 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 */
 };
-.fi
+.EE
 .in
-
+.IP
 This is the first request sent by the kernel to the daemon.
 It is used to negotiate the protocol version and other filesystem parameters.
 Note that the protocol version may affect the layout of any structure
@@ -138,14 +138,14 @@ and flags for each session.
 As of the writing of this man page,
 the highest supported kernel protocol version is
 .IR 7.26 .
-
+.IP
 Users should be aware that the descriptions in this manual page
 may be incomplete or incorrect for older or more recent protocol versions.
-
+.IP
 The reply for this request has the following format:
-
+.IP
 .in +4n
-.nf
+.EX
 struct fuse_init_out {
     uint32_t major;
     uint32_t minor;
@@ -158,9 +158,9 @@ struct fuse_init_out {
     uint32_t time_gran;       /* Since v7.6 */
     uint32_t unused[9];
 };
-.fi
+.EE
 .in
-
+.IP
 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
@@ -171,50 +171,50 @@ The kernel will then issue a new
 request conforming to the older version.
 In the reverse case, the daemon should
 quietly fall back to the kernel's major version.
-
+.IP
 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
-
+.IP
 .in +4n
-.nf
+.EX
 struct fuse_getattr_in {
     uint32_t getattr_flags;
     uint32_t dummy;
     uint64_t fh;      /* Set only if
                          (getattr_flags & FUSE_GETATTR_FH)
 };
-.fi
+.EE
 .in
-
+.IP
 The requested operation is to compute the attributes to be returned
 by
 .BR stat (2)
-and similar operations for the given file system object.
+and similar operations for the given filesystem object.
 The object for which the attributes should be computed is indicated
 either by
 .IR header\->nodeid
 or, if the
 .IR FUSE_GETATTR_FH
 flag is set, by the file handle
-.IR fh.
+.IR fh .
 The latter case of operation is analogous to
 .BR fstat (2).
-
+.IP
 For performance reasons, these attributes may be cached in the kernel for
 a specified duration of time.
 While the cache timeout has not been exceeded,
 the attributes will be served from the cache and will not cause additional
 .B FUSE_GETATTR
 requests.
-
+.IP
 The computed attributes and the requested
 cache timeout should then be returned in the following structure:
-
+.IP
 .in +4n
-.nf
+.EX
 struct fuse_attr_out {
     /* Attribute cache duration (seconds + nanoseconds) */
     uint64_t attr_valid;
@@ -239,21 +239,21 @@ struct fuse_attr_out {
         uint32_t padding;
     } attr;
 };
-.fi
+.EE
 .in
-
+.IP
 .TP
 .BR FUSE_ACCESS
-
+.IP
 .in +4n
-.nf
+.EX
 struct fuse_access_in {
     uint32_t mask;
     uint32_t padding;
 };
-.fi
+.EE
 .in
-
+.IP
 If the
 .I default_permissions
 mount options is not used, this request may be used for permissions checking.
@@ -266,15 +266,15 @@ may be indicated by returning
 .TP
 .BR FUSE_OPEN " and " FUSE_OPENDIR
 .in +4n
-.nf
+.EX
 struct fuse_open_in {
     uint32_t flags;     /* The flags that were passed
                            to the open(2) */
     uint32_t unused;
 };
-.fi
+.EE
 .in
-
+.IP
 The requested operation is to open the node indicated by
 .IR header\->nodeid .
 The exact semantics of what this means will depend on the
@@ -284,19 +284,19 @@ filesystem should validate that the requested
 .I flags
 are valid for the indicated resource and then send a reply with the
 following format:
-
+.IP
+.IP
 .in +4n
-.nf
-
+.EX
 struct fuse_open_out {
     uint64_t fh;
     uint32_t open_flags;
     uint32_t padding;
 };
-
-.fi
+.EE
 .in
-
+.IP
+.IP
 The
 .I fh
 field is an opaque identifier that the kernel will use to refer
@@ -318,9 +318,9 @@ The file is not seekable.
 .RE
 .TP
 .BR FUSE_READ " and " FUSE_READDIR
+.IP
 .in +4n
-.nf
-
+.EX
 struct fuse_read_in {
     uint64_t fh;
     uint64_t offset;
@@ -330,10 +330,10 @@ struct fuse_read_in {
     uint32_t flags;
     uint32_t padding;
 };
-
-.fi
+.EE
 .in
-
+.IP
+.IP
 The requested action is to read up to
 .I size
 bytes of the file or directory, starting at
@@ -342,13 +342,13 @@ The bytes should be returned directly following the usual reply header.
 .TP
 .BR FUSE_INTERRUPT
 .in +4n
-.nf
+.EX
 struct fuse_interrupt_in {
     uint64_t unique;
 };
-.fi
+.EE
 .in
-
+.IP
 The requested action is to cancel the pending operation indicated by
 .IR unique .
 This request requires no response.
@@ -368,9 +368,9 @@ Directly following the header is a filename to be looked up in the directory
 indicated by
 .IR header\->nodeid .
 The expected reply is of the form:
-
+.IP
 .in +4n
-.nf
+.EX
 struct fuse_entry_out {
     uint64_t nodeid;            /* Inode ID */
     uint64_t generation;        /* Inode generation */
@@ -380,15 +380,15 @@ struct fuse_entry_out {
     uint32_t attr_valid_nsec;
     struct fuse_attr attr;
 };
-.fi
+.EE
 .in
-
+.IP
 The combination of
 .I nodeid
 and
 .I generation
 must be unique for the filesystem's lifetime.
-
+.IP
 The interpretation of timeouts and
 .I attr
 is as for
@@ -396,16 +396,16 @@ is as for
 .TP
 .BR FUSE_FLUSH
 .in +4n
-.nf
+.EX
 struct fuse_flush_in {
     uint64_t fh;
     uint32_t unused;
     uint32_t padding;
     uint64_t lock_owner;
 };
-.fi
+.EE
 .in
-
+.IP
 The requested action is to flush any pending changes to the indicated
 file handle.
 No reply data is expected.
@@ -414,16 +414,16 @@ still needs to be issued once the flush operation is complete.
 .TP
 .BR FUSE_RELEASE " and " FUSE_RELEASEDIR
 .in +4n
-.nf
+.EX
 struct fuse_release_in {
     uint64_t fh;
     uint32_t flags;
     uint32_t release_flags;
     uint64_t lock_owner;
 };
-.fi
+.EE
 .in
-
+.IP
 These are the converse of
 .BR FUSE_OPEN
 and
@@ -443,9 +443,9 @@ This operation implements
 for this filesystem.
 There is no input data associated with this request.
 The expected reply data has the following structure:
-
+.IP
 .in +4n
-.nf
+.EX
 struct fuse_kstatfs {
     uint64_t blocks;
     uint64_t bfree;
@@ -462,23 +462,34 @@ struct fuse_kstatfs {
 struct fuse_statfs_out {
     struct fuse_kstatfs st;
 };
-.fi
+.EE
 .in
-
+.IP
 For the interpretation of these fields, see
 .BR statfs (2).
 .SH ERRORS
 .TP
-.B EPERM
-Returned from operations on a
-.I /dev/fuse
-file descriptor that has not been mounted.
+.B E2BIG
+Returned from
+.BR read (2)
+operations when the kernel's request is too large for the provided buffer
+and the request was
+.BR FUSE_SETXATTR .
+.TP
+.B EINVAL
+Returned from
+.BR write (2)
+if validation of the reply failed.
+Not all mistakes in replies will be caught by this validation.
+However, basic mistakes, such as short replies or an incorrect
+.I unique
+value, are detected.
 .TP
 .B EIO
 Returned from
 .BR read (2)
 operations when the kernel's request is too large for the provided buffer.
-
+.IP
 .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
@@ -493,35 +504,25 @@ for an inode that has previously been reported to the kernel; or
 giving replies to the kernel that are shorter than what the kernel expected.
 .RE
 .TP
-.B EINVAL
-Returned from
-.BR write (2)
-if validation of the reply failed.
-Not all mistakes in replies will be caught by this validation.
-However, basic mistakes, such as short replies or an incorrect
-.I unique
-value, are detected.
-.TP
-.B E2BIG
-Returned from
-.BR read (2)
-operations when the kernel's request is too large for the provided buffer
-and the request was
-.BR FUSE_SETXATTR .
-.TP
 .B ENODEV
 Returned from
 .BR read (2)
 and
 .BR write (2)
 if the FUSE filesystem was unmounted.
+.TP
+.B EPERM
+Returned from operations on a
+.I /dev/fuse
+file descriptor that has not been mounted.
 .SH CONFORMING TO
 The FUSE filesystem is Linux-specific.
 .SH NOTES
 The following messages are not yet documented in this manual page:
+.PP
 .\" FIXME: Document the following.
-.in +8n
-.nf
+.in +4n
+.EX
 .BR FUSE_BATCH_FORGET
 .BR FUSE_BMAP
 .BR FUSE_CREATE
@@ -552,7 +553,7 @@ The following messages are not yet documented in this manual page:
 .BR FUSE_SYMLINK
 .BR FUSE_UNLINK
 .BR FUSE_WRITE
-.fi
+.EE
 .in
 .SH SEE ALSO
 .BR fusermount (1),