propp

1. FUSE Protocol

This chapter describes the procotol used between the FUSE kernel module and the program providing a file system. All comminication is done through a special file descriptor.

[FIXME: add more here about stuffs]

In the rest of this chapter, the term `node' refers to either a file or directory.

The version of the FUSE protocol described in this document is version 3.1.

1.1 Kernel requests

The kernel sends requests by writing a special structure to the communication file descriptor. The structure contains an unique identifier that is used to seprate the requests from other parallel requests taking place around the same time. In full, the structure contains the following members:

uint32_t unique

The identifier used to identify the requests. Replies to the request must provide the exact same unique identifier.

uint32_t opcode

Member to specify request type. See table below for definitions.

uint32_t ino

Inode number of the file or directory that the request corresponds to. The root of the file system has inode number 1.

uint32_t uid

uint32_t gid

uint32_t pid

Credential information; on who's behalf is the request done.

The structure is mandatory for all requests. Following the structure data is any optional data.

Request opcodes initiated by the kernel:

Replies simply contain the unique request identifier, an error code (zero means success) and any optional data. Error codes are standard POSIX errno values, but negative (e.g., -ENOMEM.) Reply header:

uint32_t unique

Unique request identifier

uint32_t error

Error code. Zero means success.

One common data structure for an reply is the `entry' structure. This structure describes a node in the file system. The kernel do not have to have any previous knowledge about the node. For the kernel to ever make an request to a node, it must have first been told about it through a `entry' structure (or a directory entry.) With the exception of the root node.

uint32_t ino

The inode number of the node.

uint32_t generation

Inode generation. The generation count is incremented every time the inode counter wraps around. The tuple <ino, generation> must be unique through the lifetime of the file system.

uint32_t entry_valid_sec, entry_valid_usec

Specifies for how long the node is valid, before the kernel has to re-request information about it.

uint32_t attr_valid_sec, attr_valid_usec

Specifies for how long the information in attr is valid, before the kernel has to re-request it with a getattr request.

attr

Attributes of the node. This structure is more or less a stripped down version of stat. The following members are available:

uint32_t mode

uint32_t nlink

uint32_t uid

uint32_t gid

uint32_t rdev

uint64_t size

uint32_t blocks

uint32_t atime_sec, atime_usec

uint32_t mtime_sec, mtime_usec

uint32_t ctime_sec, ctime_usec

The members corresponds to the members of the `stat' structure.

1.2 LOOKUP: Find node in directory

Following the request structure is the name, name, of an node that the kernel wants to retrieve information about. The node should live in the directory specified by ino in the request.

If the directory do not have node with the name given in name it should return ENOENT.

If the lookup were successful a full `entry' structure should be returned, describing the node.

1.3 FORGET: Flush information about a node

The kernel tells the file system that there is no longer any need to keep information in memory about the node specified by ino.

The file system should not send any reply to this request.

1.4 GETATTR: Get a node's attributes

The file system should return attribute information about the node specified by ino, in the form of an attribute structure.

If for some reason ino is no longer valid, ENOENT should be returned.

1.5 SETATTR: Update a node's attributes

This request is the direct opposite to GETATTR. Following the request structure is an attribute structure that defines the new attributes of the node.

The file system may choose to reject the changes by returning ENOENT, EPERM or any other error code.

1.6 READLINK: Read value of a symbolic link

The file system should return the value of the symbolic link specified by INO. The reply should contain a null-terminated string, which represents the value of the link. If the node is not a symbolic link, or in the case of some other error, the file system is free to reply with an error code and no value.

1.7 GETDIR: Get directory contents

This request is one of the more complex ones of the FUSE protocol. The file system should reply with a file descriptor holding directory entries for the directory given by INO. The directory entry structure maps relatively well to the POSIX dirent structure. Each directory entry contains the following members:

ino_t ino

The inode number of the node the entry represents.

uint16_t namelen

The length in bytes of the null-terminated string describing the name of the node.

uint8_t type

Gives the node type. [FIXME: More information here.]

char name[256]

Null-terminated string representing name of the node. The 256-byte limit on this member enforces a 255-byte limit on the name of a directory entry.

The file system can cache the file used for storing the directory entries, and do lazy-updates of it is known that the state of the under-laying directory has changed.

If node given by ino is not a directory, or the file system encounters any other problem while retrieving the directory entries, it is free to reply with an error code.

1.8 MKNOD: Create a file

The mknod request is used to create files that are not directories (which is created with the mkdir request.) Following the request header is three arguments:

uint32_t mode

Specifies both the permissions to use and the type of node to be created.

uint32_t rdev

If mode is `S_IFCHR' or `S_IFBLK' then dev specifies the major and minor numbers of the newly created device special file; otherwise it is ignored.

char name[]

Name of the new node.

If pathname already exists, or is a symbolic link, this call fails with an EEXIST error.

The newly created node should be owned by the credentials information provided by uid and gid.

1.9 MKDIR: Create a directory

Request file system to create a new directory in the under-laying directory specified by ino. Directly following the request header is a 32-bit value specifying the `mode' of the directory that should be created. Back-to-back with mode is the name of the directory, which is represented using a null-terminated string.

The file system should either return with an error code, or a `entry' structure describing the newly created directory.

1.10 UNLINK: Delete a name and possible the file it refers to

Delete the node specified by ino from the file system. The file system should simply acknowledge the request, or reply with an error code.

1.11 RMDIR: Delete a directory

The kernel requests that the file system should remove the directory given by ino. The file system should simply acknowledge the request, or reply with an error code.

1.12 SYMLINK: Make a new name for a node

Following the request structure is a null-terminated string that be the target of the symbolic link. The file system should respond either with an error code or an `entry' structure describing the new symbolic link node.

1.13 RENAME: Change the name of a node

The rename request renames a file, moving it between directories if required. ino corresponds to the directory where node is currently living in. The request takes the following arguments:

ino_t newdir

The inode number of the new directory where the file will live. If the node is in fact not a directory, the file system may respond with a ENOTDIR error code.

char oldname[]

The old name of the node, living in ino.

char newname[]

The new name that will be associated with the node.

Both oldname and newname are null-terminated strings.

1.14 LINK: Make a new name for a node

[FIXME!]

1.15 OPEN: Open a file

Open file specified by ino. Creation or truncation flags (i.e., O_CREAT, O_EXCL, O_TRUNC) will not be passed with this request. The file system should only check if the operation is permitted given the user credentials and mode (following directly after the request structure.) The file system should respond with an error code (zero on success) and a file handle that will be used to hold per-open information. The file handle is a 32-bit counter that will be passed to corresponding read, write, release and flush requests.

1.16 FLUSH: Flush contents of file

The file system is provided the per-open handler returned from a previous open request. ino is used to identify the node.

This request informs the file system that any dirty data should be written to disk.

1.17 RELEASE: Release a file handle

The kernel releases a reference to a per-open handler returned from a previous open request. Following the file handle is a 32-bit word flag word, describing the mode of the file. This mode is the same mode as the file were opened.

A release request is sent when an open file has:

• all file descriptos closed, and

• all memory mappings unmapped

The file system should not send any replies to a release request.

1.18 READ: Read data from a file

The file system should return data from file identifier by ino and the provided file handle. The file system is not forced to return the specified amount of data.

uint32_t file_handle

The per-open file handle, returned from a previous open request.

uint64_t offset

Offset into the file where the read should be performed.

uint32_t size

Number of bytes to read.

The file system should reply with a normal reply header, following the read data. The length of the reply specifies the total number of bytes read from the file.

1.19 WRITE: Write data to a file

The kernel provides data that should be written to a file. The request contains the following members:

uint32_t write_page

Nonzero if this write request originates from a write to a mmaped page.

uint32_t file_handle

The per-open file handle, returned from a previous open request.

uint64_t offset

Offset into the file where the read should be performed.

uint32_t size

Number of bytes to read.

data[]

Data to be written. The length of the variable array is determined by size argument.

The file system should respond with reply with an error code and the amount of data that were written.

1.20 STATFS: Get file system status

The file system should reply with a structure containing status, statistics and parameters of the file system. The structure has the following members:

uint32_t bsize

Optimal transfer block size.

uint64_t blocks

Total data blocks in the file system.

uint64_t bfree

Free blocks in the file system.

uint64_t bavail

Free blocks available to non-superuser.

uint64_t files

Total file nodes in the file system.

uint64_t ffree

Free file nodes in the file system.

uint32_t namelen

Maximum length of filenames.

1.21 FSYNC: Synchronize a node's in-core state with disk

Sync the contents of node that the per-open provided file handler corresponds to. The node is also identified by ino. The kernel provides an extra flag: datasync. If datasync is nonzero, the file system should only flush user data, not the meta data such as `mtime' and `atime'.

1.22 SETXATTR

1.23 GETXATTR

1.24 LISTXATTR,

1.25 REMOVEXATTR,

Table of Contents

1. FUSE Protocol

1.1 Kernel requests
1.2 LOOKUP: Find node in directory
1.3 FORGET: Flush information about a node
1.4 GETATTR: Get a node's attributes
1.5 SETATTR: Update a node's attributes
1.6 READLINK: Read value of a symbolic link
1.7 GETDIR: Get directory contents
1.8 MKNOD: Create a file
1.9 MKDIR: Create a directory
1.10 UNLINK: Delete a name and possible the file it refers to
1.11 RMDIR: Delete a directory
1.12 SYMLINK: Make a new name for a node
1.13 RENAME: Change the name of a node
1.14 LINK: Make a new name for a node
1.15 OPEN: Open a file
1.16 FLUSH: Flush contents of file
1.17 RELEASE: Release a file handle
1.18 READ: Read data from a file
1.19 WRITE: Write data to a file
1.20 STATFS: Get file system status
1.21 FSYNC: Synchronize a node's in-core state with disk
1.22 SETXATTR
1.23 GETXATTR
1.24 LISTXATTR,
1.25 REMOVEXATTR,

Short Table of Contents

1. FUSE Protocol

About this document

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four