FUSE Library Options and High- and Low-Level APIs

This page contains two online appendices for the paper "Performance and Resource Utilization of FUSE User-Space File Systems" published in ACM Transactions on Storage, Volume X, Issue Y. Appendix A describes FUSE library high-level and low-level options while Appendix B details high-level and low-level APIs.

Appendix A. FUSE Library Options

We describe here the various mount options (arguments) present in FUSE library that can be utilized (passed as arguments) by the file system owners during mount. Table 1 shows the various options/optimizations, their meaning, and their default values provided by the high-level API. These optimizations are implemented in the high-level API layer and they are not communicated to the kernel driver. Only file systems implemented using the high-level API can utilize these options. Table 2 shows the various optimizations/options, their meaning, and their default values provided by the low-level API. These optimizations are implemented in the low-level API layer and are communicated with the kernel driver during the init request processing. These options are available to file systems implemented by high-level and low-level FUSE APIs.

Table (1) High-level FUSE library options

Option Description Default Value
ac_attr_timeout The length of time that file attributes are cached, when checking if auto_cache should flush data on open (type "double") 0.0 secs
attr_timeout The length of time in seconds that file/directory attributes are cached (type "double") 1.0 sec
auto_cache Enable automatic flushing of data cache on open 0 (False)
-d, debug Debug: log all the operations 0 (Disabled)
direct_io Enable Direct I/O (bypassing page cache) 0 (Disabled)
entry_timeout The length of time in seconds that name lookups will be cached (type "double") 1.0 sec
gid Override the st_gid field set by the file system with argument passed 0 (False)
-h, --help Prints help for this group of options 0 (Do not Print)
hard_remove Remove the file on unlink instead of creating a hidden file 0 (Disabled)
intr Allow requests to be interrupted 0 (Disabled)
intr_signal Which signal number to send to the file system when a request is interrupted SIGUSR1
kernel_cache Disables flushing the cache of the file contents on every open 0 (False)
modules Names of modules to push onto the file system stack NULL
negative_timeout The length of time in seconds that a negative lookup will be cached (type "double") 0.0 secs
noforget Never forget cached inodes 0 (means False)
nullpath_ok If this is enabled, the following operations do not require path information: read, write, flush, release, fsync, readdir, releasedir, fsyncdir, lock, ioctl, and poll. They will depend on the fuse_file_info structure's fh value instead. This option might be useful for cases when a file is unlinked and then read or writes are performed on it. 0 (Disabled)
readdir_ino If use_ino option is not given, still try to fill in the d_ino field in readdir 0 (Disabled)
remember Remember cached inodes for that many seconds (type "int") 0 secs
uid Override the st_uid field set by the file system with argument passed 0 (False)
umask Override the permission bits in st_mode set by the file system, given in octal 0 (False)
use_ino Honor the st_ino field in kernel functions getattr and fill_dir. Used in cases like hardlinks where the same inode number has to be reported for all hardlinked entities. Note that FUSE maintains its own "node ID" for each entity. 0 (Disabled)

Table (2) Low-Level FUSE library Options

Option Description Default Value
allow_root File access is limited to the user mounting the file system and root 0 (Disabled)
async_dio Asynchronous direct I/O 0 (False)
async_read Perform reads asynchronously 1 (Enabled)
atomic_o_trunc Enable atomic open and truncate support 0 (False)
auto_inval_data Use automatic kernel cache invalidation logic 0 (False)
big_writes Enable larger than 4KB writes 0 (False)
clone_fd Separate /dev/fuse device file descriptor for each processing thread 0 (False)
congestion_threshold Kernel's congestion threshold for background requests 9 requests
-d, debug Debug 0 (Disabled)
-h, --help Prints help for this group of options 0 (Do not print)
max_background Number of maximum background requests 12 requests
max_readahead Maximum readahead 131,072 bytes
max_write Maximum size of write requests in bytes 131,072 bytes
no_remote_flock Disable remote file locking (BSD) 0 (False)
no_remote_lock Disable remote file locking 0 (False)
no_remote_posix_lock Disable remove file locking (POSIX) 0 (False)
readdirplus Control readdirplus use (yes | no | auto). The "auto" option facilitates an adaptive readdirplus, which allows file systems to switch between normal readdir and readdirplus modes. auto
splice_move Move data while splicing to the FUSE device 0 (False)
splice_read Use splice to read from the FUSE device 0 (False)
splice_write Use splice to write to the FUSE device 0 (False)
sync_read Perform reads synchronously 0 (Disabled)
time_gran Time granularity in nano-seconds (type "uint32_t") 0 secs
-V, --version Print FUSE version number 0 (Not printed)
writeback_cache Enable asynchronous, buffered writes 0 (False)

Appendix B. FUSE High-Level and Low-Level API Details

In this appendix, we describe each FUSE request type and corresponding FUSE high-level and low-level API calls, including their arguments and return values(ordered by the FUSE request/opcode ID). The high-level API returns synchronously, while low-level API is fully asynchronous.

FUSE Request ID Request Type High-Level Low-Level
1 LOOKUP None lookup
  • Arguments: request handle, inode number of the parent directory, name (of file/dir to lookup)
  • Reply: Lookup count is incremented and a reply with a directory entry is sent on success; reply with -errno is sent on failure
2 FORGET None forget
  • Arguments: request handle, inode number, number of lookups to forget
  • Reply: No reply is sent
3 GETATTR getattr, fgetaattr
  • Arguments: Pathname of the object, attributes of the stat structure to be filled
  • Return value: Returns zero for success and -errno for failure
 getattr
  • Arguments: request handle, inode number, file-information
  • Reply: Reply with object attributes upon success, and -errno upon failure
4 SETATTR chmod, chown, truncate, ftruncate, utimens
  • Arguments:
    • chmod: Pathname of the object, object's new permissions to change to
    • chown: Pathname of the object, object's owner & group values to change to
    • truncate/ftruncate: Pathname of the file, size to truncate the file to
  • Return value: Returns zero for success, and -errno for failure
setattr
  • Arguments: request handle, inode number, the attributes to set, bitmask of the attributes which must be set, file-information
  • Reply: Reply with attributes upon success, and -errno upon failure
5 READLINK readlink
  • Arguments: Path to the symbolic link, target buffer to copy the symbolic link to, size of the path to the symbolic link
  • Return value: Returns zero for success, and -errno for failure
 readlink
  • Arguments: request handle, inode number
  • Reply: Reply with contents of a symbolic link upon success, and -errno upon failure
6 SYMLINK symlink
  • Arguments: Pathname from which symbolic link is created, pathname to which symbolic link is created
  • Return value: Returns zero for success, and -errno for failure
 symlink
  • Arguments: request handle, contents of the symbolic link, inode number of the parent directory, name of the symbolic link to create
  • Reply: Reply with a directory entry upon success, and -errno upon failure
8 MKNOD mknod
  • Arguments: Pathname of the object/node, object mode to use and type of node to be created, device object
  • Return value: Returns zero for success, and -errno for failure
 mknod
  • Arguments: request handle, inode number of the parent directory, name of the object to create, file type and mode with which to create the new object, the device number (only valid if created file is a device)
  • Reply: Reply with a directory entry upon success, and -errno upon failure
9 MKDIR mkdir
  • Arguments: Pathname of the directory, permissions of the directory
  • Return value:Returns zero for success, and -errno for failure
 mkdir
  • Arguments: request handle, inode number of the parent directory, name of directory to create, mode of creating directory
  • Reply: Reply with a directory entry upon success, and -errno upon failure
10 UNLINK unlink
  • Arguments: Pathname of the object
  • Return value:Returns zero for success, and -errno for failure
 unlink
  • Arguments:request handle, inode number of the parent directory, name of the file to unlink
  • Reply: Reply with zero upon success, and -errno upon failure
12 RENAME rename
  • Arguments: Pathname to rename the object from, pathname to rename the object to
  • Return value:Returns zero for success, and -errno for failure
 rename
  • Arguments:request handle, inode number of the old parent directory, old name, inode number of the new parent directory, new name
  • Reply: Reply with zero upon success, and -errno upon failure
13 LINK link
  • Arguments: Pathname to create a hardlink from, pathname to create a hardlink to
  • Return value:Returns zero for success, and -errno for failure
 link
  • Arguments:request handle, old inode number, inode number of the new parent directory, new name of the hardlink to create
  • Reply: Reply with a directory entry upon success, and -errno upon failure
14 OPEN open
  • Arguments: Pathname of the file, file-information
  • Return value: Returns zero for success, and -errno for failure
 open
  • Arguments:request handle, inode number, file-information
  • Reply: Reply with open parameters upon success, and -errno upon failure
15 READ read
  • Arguments: Pathname of the file, buffer to read into, number of bytes to read, offset to read from, file-information
  • Return value: Returns zero for success, and -errno for failure
read_buf
  • Arguments: Pathname of the file, buffer to read into (memory for buffer should be allocated dynamically), number of bytes to read, offset to read from, file-information
  • Return value:Returns zero for success, and -errno for failure
 read
  • Arguments:request handle, inode number, number of bytes to read, offset to read from, file-information
  • Reply: Reply with data or a data vector or a data copied from buffer(s) upon success. Reply with -errno upon failure
16 WRITE write
  • Arguments: Pathname of the file, buffer to write from, number of bytes to write, offset to write from, file-information
  • Return value:Returns zero for success, and -errno for failure
write_buf
  • Arguments: Pathname of the file, buffer to write from, offset to write from, file-information
  • Return value:Returns zero for success, and -errno for failure
 write
  • Arguments:request handle, inode number, data to write, number of bytes to write, offset to write to, file-information
  • Reply: Reply with the number of bytes written upon success, and -errno upon failure
write_buf
  • Arguments:request handle, inode number, buffer containing the data, offset to write to, file-information
  • Reply: Reply with the number of bytes written upon success, and -errno upon failure
17 STATFS statfs
  • Arguments: Pathname of the file system, structure to record file system statistics
  • Return value:Returns zero for success, and -errno for failure
 statfs
  • Arguments:request handle, inode number
  • Reply: Reply with file system statistics upon success, and -errno upon failure
18 RELEASE release
  • Arguments: Pathname of the file to release, file-information
  • Return value:Returns zero for success, and -errno for failure
 release
  • Arguments:request handle, inode number, file-information
  • Reply: Reply with zero upon success, and -errno upon failure
20 FSYNC fsync
  • Arguments: Pathname of the file to sync to disk, flag indicating if only the data should be flushed (and not the metadata), file-information
  • Return value:Returns zero for success, and -errno for failure
 fsync
  • Arguments:request handle, inode number, flag indicating if only the data should be flushed (and not the metadata), file-information
  • Reply: Reply with zero upon success, and -errno upon failure
21 SETXATTR setxattr
  • Arguments: Pathname of the object, name of the extended attribute to set, value of the extended attribute, size of the value to set, flags to indicate if extended attribute has to be newly created or just its value replaced
  • Return value:Returns zero for success, and -errno for failure
 setxattr
  • Arguments:request handle, inode number, name of the extended attribute to set, value of the extended attribute, size of the value to set, flags to indicate if extended attribute has to be newly created or just its value replaced
  • Reply: Reply with zero upon success, and -errno upon failure
22 GETXATTR getxattr
  • Arguments: Pathname of the object, name of the extended attribute to get, value of the extended attribute, size of the value to get
  • Return value:Returns zero for success, and -errno for failure
 getxattr
  • Arguments:request handle, inode number, name of the extended attribute to get, size of the value of the extended attribute
  • Reply: Reply with data, or data copied from buffer(s), or needed buffer size upon success. Reply with -errno upon failure
23 LISTXATTR listxattr
  • Arguments: Pathname of the object whose extended attributes must be listed, list containing the name and corresponding values of extended attributes, maximum size of the list to send
  • Return value:Returns zero for success, and -errno for failure
 listxattr
  • Arguments:request handle, inode number, maximum size of the list to send
  • Reply: Reply with data, or data copied from buffer(s), or needed buffer size upon success. Reply with -errno upon failure
24 REMOVEXATTR removexattr
  • Arguments: Pathname of the object, name of the extended attribute to remove
  • Return value:Returns zero for success, and -errno for failure
 removexattr
  • Arguments:request handle, inode number, name of the extended attribute to remove
  • Reply: Reply with zero upon success, and -errno upon failure
25 FLUSH flush
  • Arguments: Pathname of the object, file-information
  • Return value:Returns zero for success, and -errno for failure
 flush
  • Arguments:request handle, inode number, file-information
  • Reply: Reply with zero upon success, and -errno upon failure
26 INIT init
  • Arguments: structure that gives information about supported features in FUSE and can be used to request certain capabilities when the FUSE library establishes communication with the kernel module
  • Return value:Returns zero for success, and -errno for failure
 init
  • Arguments:user data to be passed from the FUSE library to the FUSE kernel, information about supported features in FUSE which is provided when the FUSE library establishes communication with the kernel module
  • Reply: No reply is sent
27 OPENDIR opendir
  • Arguments: Pathname of the directory, file-information
  • Return value:Returns zero for success, and -errno for failure
 opendir
  • Arguments: request handle, inode number, file-information
  • Reply: Reply with open parameters upon success, and -errno upon failure
28 READDIR readdir
  • Arguments: Pathname of the directory, buffer to read the directory stream to, pointer to a filler function to add an entry during a readdir operation, offset to continue reading the directory stream from, file-information
  • Return value:Returns zero for success, and -errno for failure
 readdir
  • Arguments: request handle, inode number, maximum number of bytes to send, offset to continue reading the directory stream from, file-information
  • Reply: Reply with data, or data copied from buffer(s) upon success. Reply with -errno upon failure
29 RELEASEDIR releasedir
  • Arguments: Pathname of the directory, file-information
  • Return value:Returns zero for success, and -errno for failure
 releasedir
  • Arguments:request handle, inode number, file-information
  • Reply: Reply with zero upon success, and -errno upon failure
30 FSYNCDIR fsyncdir
  • Arguments: Pathname of the directory, flag indicating if only data should be flushed (and not the metadata), file-information
  • Return value:Returns zero for success, and -errno for failure
 fsyncdir
  • Arguments:request handle, inode number, flag indicating if only data should be flushed (and not the metadata), file-information
  • Reply: Reply with zero upon success, and -errno upon failure
31 GETLK lock
  • Arguments: Pathname of the file, file-information, command to indicate getting of a POSIX file lock, file lock object
  • Return value:Returns zero for success, and -errno for failure
 getlk
  • Arguments:request handle, inode number, file-information, the region/type to test for a POSIX lock
  • Reply: Reply with file lock information upon success, and -errno upon failure
32 SETLK lock
  • Arguments: Pathname of the file, file-information, command to indicate setting of a POSIX file lock, file lock object
  • Return value:Returns zero for success, and -errno for failure
 flock
  • Arguments:request handle, inode number, file-information, the locking operation
  • Reply: Reply with zero upon success, and -errno upon failure
setlk
  • Arguments:request handle, inode number, file-information, region/type to acquire or modify or release a POSIX lock, sleep time for locking operation
  • Reply: Reply with zero upon success, and -errno upon failure
33 SETLKW lock
  • Arguments: Pathname of the file, file-information, command to indicate setting of a POSIX file lock, file lock object
  • Return value: Returns zero for success, and -errno for failure
 flock
  • Arguments:request handle, inode number, file-information, the locking operation
  • Reply: Reply with zero upon success, and -errno upon failure
setlk
  • Arguments:request handle, inode number, file-information, region/type to acquire or modify or release a POSIX lock, sleep time for locking operation
  • Reply: Reply with zero upon success, and -errno upon failure
34 ACCESS access
  • Arguments: Pathname of the object, requested access mode
  • Return value:Returns zero for success, and -errno for failure
 access
  • Arguments: request handle, inode number, requested access mode
  • Reply: Reply with zero upon success, and -errno upon failure
35 CREATE mknod
  • Arguments: Pathname to create non-directory non-symlink nodes, mode with which to create the nodes, device object associated with a device node
  • Return value:Returns zero for success, and -errno for failure
 create
  • Arguments: request handle, parent inode number of the parent directory, name to create, file type and mode with which to create the new file, file-information
  • Reply: Reply with a directory entry and open parameters, and increments the lookup count, upon success. Reply with -errno upon failure
37 BMAP bmap
  • Arguments: Pathname of the block device, block size, block index
  • Return value:Returns zero for success, and -errno for failure
 bmap
  • Arguments:request handle, inode number, unit of block index, block index within file
  • Reply: Reply with block index upon success, and -errno upon failure
38 DESTROY destroy
  • Arguments: FUSE context information
  • Return value:Returns zero for success, and -errno for failure
 destroy
  • Arguments: user data passed from the FUSE library to the FUSE kernel (by when the connection to it may have gone already)
  • Reply: No reply is sent
39 IOCTL ioctl
  • Arguments: Pathname of the object, ioctl command, ioctl arguments, file-information, FUSE_IOCTL_* flags, data fetched from the caller
  • Return value:Returns zero for success, and -errno for failure
 ioctl
  • Arguments:request handle, inode number, ioctl command, ioctl arguments, file-information, FUSE_IOCTL_* flags, data fetched from the caller, number of fetched bytes, maximum size of output data
  • Reply: Reply to ask for input data to be fetched in order to retry/finish ioctl, and prepare the output buffer, upon success. Reply with -errno upon failure
40 POLL poll
  • Arguments: Pathname of the object, file-information, poll handle to be used for notification, event pertaining to polling
  • Return value:Returns zero for success, and -errno for failure
 poll
  • Arguments:request handle, inode number, file-information, poll handle to be used for notification
  • Reply: Reply with poll result event mask upon success, and -errno upon failure
41 NOTIFY_REPLY None retrieve_reply
  • Arguments:request handle, user data supplied on to the callback function for the retrieve request, inode number supplied, offset supplied, buffer containing the returned data
  • Reply: No reply is sent
42 BATCH_FORGET None forget_multi
  • Arguments: request handle, count of inodes to forget, individual forget objects
  • Reply: No reply is sent
forget
  • Arguments: request handle, inode number, number of lookups to forget
  • Reply: No reply is sent
43 FALLOCATE fallocate
  • Arguments: Pathname of the file, operation to be performed on the given range, starting point for allocated region, size of the allocated region, file-information
  • Return value:Returns zero for success, and -errno for failure
 fallocate
  • Arguments: request handle, inode number, starting point for allocated region, size of the allocated region, operation to be performed on the given range
  • Reply: Reply with zero upon success, and -errno upon failure
44 READDIRPLUS None readdirplus
  • Arguments: request handle, inode number, maximum number of bytes to send, offset to continue reading the directory stream from, file-information
  • Reply: Reply with data, or data copied from buffer(s), upon success. Reply with -errno upon failure
45 RENAME2 rename
  • Arguments: Pathname to rename the object from, pathname to rename the object to
  • Return value:Returns zero for success, and -errno for failure
 rename
  • Arguments: request handle, parent inode number of the old parent directory, old name, inode number of the new parent directory, new name
  • Reply: Reply with zero upon success, and -errno upon failure

(c) Stony Brook University 2018-10-29