libfuse

Data Structures | Macros | Enumerations | Functions
fuse_common.h File Reference
`#include <stdbool.h>`
`#include "libfuse_config.h"`
`#include "fuse_opt.h"`
`#include "fuse_log.h"`
`#include <stdint.h>`
`#include <sys/types.h>`
`#include <assert.h>`

Go to the source code of this file.

## Data Structures
struct | fuse_file_info
struct | fuse_loop_config
struct | fuse_conn_info
struct | fuse_buf
struct | fuse_bufvec
struct | libfuse_version

## Macros
#define | FUSE_IOCTL_COMPAT (1 << 0)
#define | FUSE_BACKING_STACKED_UNDER (0)

## Enumerations
enum | fuse_capability { FUSE_CAP_ASYNC_READ = (1 << 0) , FUSE_CAP_POSIX_LOCKS = (1 << 1) , FUSE_CAP_ATOMIC_O_TRUNC = (1 << 3) , FUSE_CAP_EXPORT_SUPPORT = (1 << 4) , FUSE_CAP_DONT_MASK = (1 << 6) , FUSE_CAP_SPLICE_WRITE = (1 << 7) , FUSE_CAP_SPLICE_MOVE = (1 << 8) , FUSE_CAP_SPLICE_READ = (1 << 9) , FUSE_CAP_FLOCK_LOCKS = (1 << 10) , FUSE_CAP_IOCTL_DIR = (1 << 11) , FUSE_CAP_AUTO_INVAL_DATA = (1 << 12) , FUSE_CAP_READDIRPLUS = (1 << 13) , FUSE_CAP_READDIRPLUS_AUTO = (1 << 14) , FUSE_CAP_ASYNC_DIO = (1 << 15) , FUSE_CAP_WRITEBACK_CACHE = (1 << 16) , FUSE_CAP_NO_OPEN_SUPPORT = (1 << 17) , FUSE_CAP_PARALLEL_DIROPS = (1 << 18) , FUSE_CAP_POSIX_ACL = (1 << 19) , FUSE_CAP_HANDLE_KILLPRIV = (1 << 20) , FUSE_CAP_HANDLE_KILLPRIV_V2 = (1 << 21) , FUSE_CAP_CACHE_SYMLINKS = (1 << 23) , FUSE_CAP_NO_OPENDIR_SUPPORT = (1 << 24) , FUSE_CAP_EXPLICIT_INVAL_DATA = (1 << 25) , FUSE_CAP_EXPIRE_ONLY = (1 << 26) , FUSE_CAP_SETXATTR_EXT = (1 << 27) , FUSE_CAP_DIRECT_IO_ALLOW_MMAP = (1 << 28) , FUSE_CAP_PASSTHROUGH = (1 << 29) , FUSE_CAP_NO_EXPORT_SUPPORT = (1 << 30) , FUSE_CAP_CURRENT_MAX }
enum | fuse_buf_flags { FUSE_BUF_IS_FD = (1 << 1) , FUSE_BUF_FD_SEEK = (1 << 2) , FUSE_BUF_FD_RETRY = (1 << 3) }
enum | fuse_buf_copy_flags { FUSE_BUF_NO_SPLICE = (1 << 1) , FUSE_BUF_FORCE_SPLICE = (1 << 2) , FUSE_BUF_SPLICE_MOVE = (1 << 3) , FUSE_BUF_SPLICE_NONBLOCK = (1 << 4) }

## Functions
struct fuse_conn_info_opts * | fuse_parse_conn_info_opts (struct fuse_args *args)
void | fuse_apply_conn_info_opts (struct fuse_conn_info_opts *opts, struct fuse_conn_info *conn)
int | fuse_daemonize (int foreground)
int | fuse_version (void)
const char * | fuse_pkgversion (void)
void | fuse_pollhandle_destroy (struct fuse_pollhandle *ph)
size_t | fuse_buf_size (const struct fuse_bufvec *bufv)
ssize_t | fuse_buf_copy (struct fuse_bufvec *dst, struct fuse_bufvec *src, enum fuse_buf_copy_flags flags)
int | fuse_set_signal_handlers (struct fuse_session *se)
int | fuse_set_fail_signal_handlers (struct fuse_session *se)
void | fuse_remove_signal_handlers (struct fuse_session *se)

## Macro Definition Documentation

## ◆ FUSE_BACKING_STACKED_UNDER

#define FUSE_BACKING_STACKED_UNDER (0)

When FUSE_CAP_PASSTHROUGH is enabled, this is the maximum allowed stacking depth of the backing files. In current kernel, the maximum allowed stack depth if FILESYSTEM_MAX_STACK_DEPTH (2), which includes the FUSE passthrough layer, so the maximum stacking depth for backing files is 1.

The default is FUSE_BACKING_STACKED_UNDER (0), meaning that the backing files cannot be on a stacked filesystem, but another stacked filesystem can be stacked over this FUSE passthrough filesystem.

Set this to FUSE_BACKING_STACKED_OVER (1) if backing files may be on a stacked filesystem, such as overlayfs or another FUSE passthrough. In this configuration, another stacked filesystem cannot be stacked over this FUSE passthrough filesystem.

Definition at line 682 of file fuse_common.h.

## ◆ FUSE_IOCTL_COMPAT

#define FUSE_IOCTL_COMPAT (1 << 0)

Ioctl flags

FUSE_IOCTL_COMPAT: 32bit compat ioctl on 64bit machine FUSE_IOCTL_UNRESTRICTED: not restricted to well-formed ioctls, retry allowed FUSE_IOCTL_RETRY: retry with new iovecs FUSE_IOCTL_DIR: is a directory

FUSE_IOCTL_MAX_IOV: maximum of in_iovecs + out_iovecs

Definition at line 537 of file fuse_common.h.

## Enumeration Type Documentation

## ◆ fuse_buf_copy_flags

enum fuse_buf_copy_flags

Buffer copy flags

Enumerator
FUSE_BUF_NO_SPLICE | Don't use splice(2) Always fall back to using read and write instead of splice(2) to copy data from one file descriptor to another. If this flag is not set, then only fall back if splice is unavailable.
FUSE_BUF_FORCE_SPLICE | Force splice Always use splice(2) to copy data from one file descriptor to another. If splice is not available, return -EINVAL.
FUSE_BUF_SPLICE_MOVE | Try to move data with splice. If splice is used, try to move pages from the source to the destination instead of copying. See documentation of SPLICE_F_MOVE in splice(2) man page.
FUSE_BUF_SPLICE_NONBLOCK | Don't block on the pipe when copying data with splice Makes the operations on the pipe non-blocking (if the pipe is full or empty). See SPLICE_F_NONBLOCK in the splice(2) man page.

Definition at line 848 of file fuse_common.h.

## ◆ fuse_buf_flags

enum fuse_buf_flags

Buffer flags

Enumerator
FUSE_BUF_IS_FD | Buffer contains a file descriptor If this flag is set, the .fd field is valid, otherwise the .mem fields is valid.
FUSE_BUF_FD_SEEK | Seek on the file descriptor If this flag is set then the .pos field is valid and is used to seek to the given offset before performing operation on file descriptor.
FUSE_BUF_FD_RETRY | Retry operation on file descriptor If this flag is set then retry operation on file descriptor until .size bytes have been copied or an error or EOF is detected.

Definition at line 817 of file fuse_common.h.

## ◆ fuse_capability

enum fuse_capability

Enumerator
FUSE_CAP_ASYNC_READ | Indicates that the filesystem supports asynchronous read requests. If this capability is not requested/available, the kernel will ensure that there is at most one pending read request per file-handle at any time, and will attempt to order read requests by increasing offset. This feature is enabled by default when supported by the kernel.
FUSE_CAP_POSIX_LOCKS | Indicates that the filesystem supports "remote" locking. This feature is enabled by default when supported by the kernel, and if getlk() and setlk() handlers are implemented.
FUSE_CAP_ATOMIC_O_TRUNC | Indicates that the filesystem supports the O_TRUNC open flag. If disabled, and an application specifies O_TRUNC, fuse first calls truncate() and then open() with O_TRUNC filtered out. This feature is enabled by default when supported by the kernel.
FUSE_CAP_EXPORT_SUPPORT | Indicates that the filesystem supports lookups of "." and "..". When this flag is set, the filesystem must be prepared to receive requests for invalid inodes (i.e., for which a FORGET request was received or which have been used in a previous instance of the filesystem daemon) and must not reuse node-ids (even when setting generation numbers). This feature is disabled by default.
FUSE_CAP_DONT_MASK | Indicates that the kernel should not apply the umask to the file mode on create operations. This feature is disabled by default.
FUSE_CAP_SPLICE_WRITE | Indicates that libfuse should try to use splice() when writing to the fuse device. This may improve performance. This feature is disabled by default.
FUSE_CAP_SPLICE_MOVE | Indicates that libfuse should try to move pages instead of copying when writing to / reading from the fuse device. This may improve performance. This feature is disabled by default.
FUSE_CAP_SPLICE_READ | Indicates that libfuse should try to use splice() when reading from the fuse device. This may improve performance. This feature is enabled by default when supported by the kernel and if the filesystem implements a write_buf() handler.
FUSE_CAP_FLOCK_LOCKS | If set, the calls to flock(2) will be emulated using POSIX locks and must then be handled by the filesystem's setlock() handler. If not set, flock(2) calls will be handled by the FUSE kernel module internally (so any access that does not go through the kernel cannot be taken into account). This feature is enabled by default when supported by the kernel and if the filesystem implements a flock() handler.
FUSE_CAP_IOCTL_DIR | Indicates that the filesystem supports ioctl's on directories. This feature is enabled by default when supported by the kernel.
FUSE_CAP_AUTO_INVAL_DATA | Traditionally, while a file is open the FUSE kernel module only asks the filesystem for an update of the file's attributes when a client attempts to read beyond EOF. This is unsuitable for e.g. network filesystems, where the file contents may change without the kernel knowing about it. If this flag is set, FUSE will check the validity of the attributes on every read. If the attributes are no longer valid (i.e., if the attr_timeout passed to fuse_reply_attr() or set in `struct fuse_entry_param` has passed), it will first issue a `getattr` request. If the new mtime differs from the previous value, any cached file contents will be invalidated as well. This flag should always be set when available. If all file changes go through the kernel, attr_timeout should be set to a very large number to avoid unnecessary getattr() calls. This feature is enabled by default when supported by the kernel.
FUSE_CAP_READDIRPLUS | Indicates that the filesystem supports readdirplus. This feature is enabled by default when supported by the kernel and if the filesystem implements a readdirplus() handler.
FUSE_CAP_READDIRPLUS_AUTO | Indicates that the filesystem supports adaptive readdirplus. If FUSE_CAP_READDIRPLUS is not set, this flag has no effect. If FUSE_CAP_READDIRPLUS is set and this flag is not set, the kernel will always issue readdirplus() requests to retrieve directory contents. If FUSE_CAP_READDIRPLUS is set and this flag is set, the kernel will issue both readdir() and readdirplus() requests, depending on how much information is expected to be required. As of Linux 4.20, the algorithm is as follows: when userspace starts to read directory entries, issue a READDIRPLUS request to the filesystem. If any entry attributes have been looked up by the time userspace requests the next batch of entries continue with READDIRPLUS, otherwise switch to plain READDIR. This will reasult in eg plain "ls" triggering READDIRPLUS first then READDIR after that because it doesn't do lookups. "ls -l" should result in all READDIRPLUS, except if dentries are already cached. This feature is enabled by default when supported by the kernel and if the filesystem implements both a readdirplus() and a readdir() handler.
FUSE_CAP_ASYNC_DIO | Indicates that the filesystem supports asynchronous direct I/O submission. If this capability is not requested/available, the kernel will ensure that there is at most one pending read and one pending write request per direct I/O file-handle at any time. This feature is enabled by default when supported by the kernel.
FUSE_CAP_WRITEBACK_CACHE | Indicates that writeback caching should be enabled. This means that individual write request may be buffered and merged in the kernel before they are send to the filesystem. This feature is disabled by default.
FUSE_CAP_NO_OPEN_SUPPORT | Indicates support for zero-message opens. If this flag is set in the `capable` field of the `fuse_conn_info` structure, then the filesystem may return `ENOSYS` from the open() handler to indicate success. Further attempts to open files will be handled in the kernel. (If this flag is not set, returning ENOSYS will be treated as an error and signaled to the caller). Setting this flag in the `want` field enables this behavior automatically within libfuse for low level API users. If non-low level users wish to have this behavior you must return `ENOSYS` from the open() handler on supporting kernels.
FUSE_CAP_PARALLEL_DIROPS | Indicates support for parallel directory operations. If this flag is unset, the FUSE kernel module will ensure that lookup() and readdir() requests are never issued concurrently for the same directory.
FUSE_CAP_POSIX_ACL | Indicates support for POSIX ACLs. If this feature is enabled, the kernel will cache and have responsibility for enforcing ACLs. ACL will be stored as xattrs and passed to userspace, which is responsible for updating the ACLs in the filesystem, keeping the file mode in sync with the ACL, and ensuring inheritance of default ACLs when new filesystem nodes are created. Note that this requires that the file system is able to parse and interpret the xattr representation of ACLs. Enabling this feature implicitly turns on the `default_permissions` mount option (even if it was not passed to mount(2)). This feature is disabled by default.
FUSE_CAP_HANDLE_KILLPRIV | Indicates that the filesystem is responsible for unsetting setuid and setgid bits when a file is written, truncated, or its owner is changed. This feature is disabled by default.
FUSE_CAP_HANDLE_KILLPRIV_V2 | Indicates that the filesystem is responsible for unsetting setuid and setgid bit and additionally cap (stored as xattr) when a file is written, truncated, or its owner is changed. Upon write/truncate suid/sgid is only killed if caller does not have CAP_FSETID. Additionally upon write/truncate sgid is killed only if file has group execute permission. (Same as Linux VFS behavior). KILLPRIV_V2 requires handling of FUSE_OPEN_KILL_SUIDGID (set in struct fuse_create_in::open_flags) FATTR_KILL_SUIDGID (set in struct fuse_setattr_in::valid) FUSE_WRITE_KILL_SUIDGID (set in struct fuse_write_in::write_flags) This feature is disabled by default.
FUSE_CAP_CACHE_SYMLINKS | Indicates that the kernel supports caching symlinks in its page cache. When this feature is enabled, symlink targets are saved in the page cache. You can invalidate a cached link by calling: `fuse_lowlevel_notify_inval_inode(se, ino, 0, 0);` This feature is disabled by default. If the kernel supports it (>= 4.20), you can enable this feature by setting this flag in the `want` field of the `fuse_conn_info` structure.
FUSE_CAP_NO_OPENDIR_SUPPORT | Indicates support for zero-message opendirs. If this flag is set in the `capable` field of the `fuse_conn_info` structure, then the filesystem may return `ENOSYS` from the opendir() handler to indicate success. Further opendir and releasedir messages will be handled in the kernel. (If this flag is not set, returning ENOSYS will be treated as an error and signalled to the caller.) Setting this flag in the `want` field enables this behavior automatically within libfuse for low level API users. If non-low level users with to have this behavior you must return `ENOSYS` from the opendir() handler on supporting kernels.
FUSE_CAP_EXPLICIT_INVAL_DATA | Indicates support for invalidating cached pages only on explicit request. If this flag is set in the `capable` field of the `fuse_conn_info` structure, then the FUSE kernel module supports invalidating cached pages only on explicit request by the filesystem through fuse_lowlevel_notify_inval_inode() or fuse_invalidate_path(). By setting this flag in the `want` field of the `fuse_conn_info` structure, the filesystem is responsible for invalidating cached pages through explicit requests to the kernel. Note that setting this flag does not prevent the cached pages from being flushed by OS itself and/or through user actions. Note that if both FUSE_CAP_EXPLICIT_INVAL_DATA and FUSE_CAP_AUTO_INVAL_DATA are set in the `capable` field of the `fuse_conn_info` structure then FUSE_CAP_AUTO_INVAL_DATA takes precedence. This feature is disabled by default.
FUSE_CAP_EXPIRE_ONLY | Indicates support that dentries can be expired. Expiring dentries, instead of invalidating them, makes a difference for overmounted dentries, where plain invalidation would detach all submounts before dropping the dentry from the cache. If only expiry is set on the dentry, then any overmounts are left alone and until ->d_revalidate() is called. Note: ->d_revalidate() is not called for the case of following a submount, so invalidation will only be triggered for the non-overmounted case. The dentry could also be mounted in a different mount instance, in which case any submounts will still be detached.
FUSE_CAP_SETXATTR_EXT | Indicates that an extended 'struct fuse_setxattr' is used by the kernel side - extra_flags are passed, which are used (as of now by acl) processing. For example FUSE_SETXATTR_ACL_KILL_SGID might be set.
FUSE_CAP_DIRECT_IO_ALLOW_MMAP | Files opened with FUSE_DIRECT_IO do not support MAP_SHARED mmap. This restriction is relaxed through FUSE_CAP_DIRECT_IO_RELAX (kernel flag: FUSE_DIRECT_IO_RELAX). MAP_SHARED is disabled by default for FUSE_DIRECT_IO, as this flag can be used to ensure coherency between mount points (or network clients) and with kernel page cache as enforced by mmap that cannot be guaranteed anymore.
FUSE_CAP_PASSTHROUGH | Indicates support for passthrough mode access for read/write operations. If this flag is set in the `capable` field of the `fuse_conn_info` structure, then the FUSE kernel module supports redirecting read/write operations to the backing file instead of letting them to be handled by the FUSE daemon. This feature is disabled by default.
FUSE_CAP_NO_EXPORT_SUPPORT | Indicates that the file system cannot handle NFS export If this flag is set NFS export and name_to_handle_at is not going to work at all and will fail with EOPNOTSUPP.
FUSE_CAP_CURRENT_MAX | Current maximum capability value.

Definition at line 177 of file fuse_common.h.

## Function Documentation

## ◆ fuse_apply_conn_info_opts()

void fuse_apply_conn_info_opts | ( | struct fuse_conn_info_opts * | opts,
|  | struct fuse_conn_info * | conn
| ) |  |

This function applies the (parsed) parameters in opts to the conn pointer. It may modify the following fields: wants, max_write, max_readahead, congestion_threshold, max_background, time_gran. A field is only set (or unset) if the corresponding option has been explicitly set.

Definition at line 416 of file helper.c.

## ◆ fuse_buf_copy()

ssize_t fuse_buf_copy | ( | struct fuse_bufvec * | dst,
|  | struct fuse_bufvec * | src,
|  | enum fuse_buf_copy_flags | flags
| ) |  |

Copy data from one buffer vector to another

Parameters

  dst | destination buffer vector
  src | source buffer vector
  flags | flags controlling the copy

Returns
  actual number of bytes copied or -errno on error

Definition at line 284 of file buffer.c.

## ◆ fuse_buf_size()

size_t fuse_buf_size | ( | const struct fuse_bufvec * | bufv | ) |

Get total size of data in a fuse buffer vector

Parameters

  bufv | buffer vector

Returns
  size of data

Definition at line 22 of file buffer.c.

## ◆ fuse_daemonize()

int fuse_daemonize | ( | int | foreground | ) |

Go into the background

Parameters

  foreground | if true, stay in the foreground

Returns
  0 on success, -1 on failure

Definition at line 253 of file helper.c.

## ◆ fuse_parse_conn_info_opts()

struct fuse_conn_info_opts * fuse_parse_conn_info_opts | ( | struct fuse_args * | args | ) |

This function parses several command-line options that can be used to override elements of struct fuse_conn_info. The pointer returned by this function should be passed to the fuse_apply_conn_info_opts() method by the file system's init() handler.

Before using this function, think twice if you really want these parameters to be adjustable from the command line. In most cases, they should be determined by the file system internally.

The following options are recognized:

-o max_write=N sets conn->max_write -o max_readahead=N sets conn->max_readahead -o max_background=N sets conn->max_background -o congestion_threshold=N sets conn->congestion_threshold -o async_read sets FUSE_CAP_ASYNC_READ in conn->want -o sync_read unsets FUSE_CAP_ASYNC_READ in conn->want -o atomic_o_trunc sets FUSE_CAP_ATOMIC_O_TRUNC in conn->want -o no_remote_lock Equivalent to -o no_remote_flock,no_remote_posix_lock -o no_remote_flock Unsets FUSE_CAP_FLOCK_LOCKS in conn->want -o no_remote_posix_lock Unsets FUSE_CAP_POSIX_LOCKS in conn->want -o [no_]splice_write (un-)sets FUSE_CAP_SPLICE_WRITE in conn->want -o [no_]splice_move (un-)sets FUSE_CAP_SPLICE_MOVE in conn->want -o [no_]splice_read (un-)sets FUSE_CAP_SPLICE_READ in conn->want -o [no_]auto_inval_data (un-)sets FUSE_CAP_AUTO_INVAL_DATA in conn->want -o readdirplus=no unsets FUSE_CAP_READDIRPLUS in conn->want -o readdirplus=yes sets FUSE_CAP_READDIRPLUS and unsets FUSE_CAP_READDIRPLUS_AUTO in conn->want -o readdirplus=auto sets FUSE_CAP_READDIRPLUS and FUSE_CAP_READDIRPLUS_AUTO in conn->want -o [no_]async_dio (un-)sets FUSE_CAP_ASYNC_DIO in conn->want -o [no_]writeback_cache (un-)sets FUSE_CAP_WRITEBACK_CACHE in conn->want -o time_gran=N sets conn->time_gran

Known options will be removed from args, unknown options will be passed through unchanged.

Parameters

  args | argument vector (input+output)

Returns
  parsed options

Definition at line 463 of file helper.c.

## ◆ fuse_pkgversion()

const char * fuse_pkgversion | ( | void |  | ) |

Get the full package version string of the library

Returns
  the package version

Definition at line 5218 of file fuse.c.

## ◆ fuse_pollhandle_destroy()

void fuse_pollhandle_destroy | ( | struct fuse_pollhandle * | ph | ) |

Destroy poll handle

Parameters

  ph | the poll handle

Definition at line 1906 of file fuse_lowlevel.c.

## ◆ fuse_remove_signal_handlers()

void fuse_remove_signal_handlers | ( | struct fuse_session * | se | ) |

Restore default signal handlers

Resets global session. After this fuse_set_signal_handlers() may be called again.

Parameters

  se | the same session as given in fuse_set_signal_handlers()

See also: fuse_set_signal_handlers()

Definition at line 180 of file fuse_signals.c.

## ◆ fuse_set_fail_signal_handlers()

int fuse_set_fail_signal_handlers | ( | struct fuse_session * | se | ) |

Print a stack backtrace diagnostic on critical signals ()

Stores session in a global variable. May only be called once per process until fuse_remove_signal_handlers() is called.

Once either of the POSIX signals arrives, the signal handler calls fuse_session_exit().

Parameters

  se | the session to exit

Returns
  0 on success, -1 on failure

See also: fuse_remove_signal_handlers()

Definition at line 158 of file fuse_signals.c.

## ◆ fuse_set_signal_handlers()

int fuse_set_signal_handlers | ( | struct fuse_session * | se | ) |

Exit session on HUP, TERM and INT signals and ignore PIPE signal

Stores session in a global variable. May only be called once per process until fuse_remove_signal_handlers() is called.

Once either of the POSIX signals arrives, the signal handler calls fuse_session_exit().

Parameters

  se | the session to exit

Returns
  0 on success, -1 on failure

See also: fuse_remove_signal_handlers()

Definition at line 138 of file fuse_signals.c.

## ◆ fuse_version()

int fuse_version | ( | void |  | ) |

Get the version of the library

Returns
  the version

Definition at line 5213 of file fuse.c.