Module org.cryptomator.jfuse.api

Package org.cryptomator.jfuse.api

Interface FuseConnInfo

public interface FuseConnInfo

Fuse connection info struct used in FuseOperations.init(FuseConnInfo, FuseConfig) method.

This struct is a union of the libfuse2 and libfuse3 definition. If an accessor method or macro is not supported by used libfuse version, it is documented in the javadoc. See also @code{fuse_common.h} of libfuse2 or 3.

Field Summary

Fields

Modifier and Type	Field	Description
static final int	FUSE_CAP_ASYNC_DIO	Indicates that the filesystem supports asynchronous direct I/O submission.
static final int	FUSE_CAP_ASYNC_READ	Indicates that the filesystem supports asynchronous read requests.
static final int	FUSE_CAP_ATOMIC_O_TRUNC	Indicates that the filesystem supports the O_TRUNC open flag.
static final int	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.
static final int	FUSE_CAP_BIG_WRITES	Indicates that the filesystem can handle write size larger than 4kB
static final int	FUSE_CAP_CACHE_SYMLINKS	Indicates that the kernel supports caching symlinks in its page cache.
static final int	FUSE_CAP_DONT_MASK	Indicates that the kernel should not apply the umask to the file mode on create operations.
static final int	FUSE_CAP_EXPLICIT_INVAL_DATA	Indicates support for invalidating cached pages only on explicit request.
static final int	FUSE_CAP_EXPORT_SUPPORT	Indicates that the filesystem supports lookups of "." and "..".
static final int	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.
static final int	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.
static final int	FUSE_CAP_IOCTL_DIR	Indicates that the filesystem supports ioctl's on directories.
static final int	FUSE_CAP_NO_OPEN_SUPPORT	Indicates support for zero-message opens.
static final int	FUSE_CAP_NO_OPENDIR_SUPPORT	Indicates support for zero-message opendirs.
static final int	FUSE_CAP_PARALLEL_DIROPS	Indicates support for parallel directory operations.
static final int	FUSE_CAP_POSIX_ACL	Indicates support for POSIX ACLs.
static final int	FUSE_CAP_POSIX_LOCKS	Indicates that the filesystem supports "remote" locking.
static final int	FUSE_CAP_READDIRPLUS	Indicates that the filesystem supports readdirplus.
static final int	FUSE_CAP_READDIRPLUS_AUTO	Indicates that the filesystem supports adaptive readdirplus.
static final int	FUSE_CAP_SPLICE_MOVE	Indicates that libfuse should try to move pages instead of copying when writing to / reading from the fuse device.
static final int	FUSE_CAP_SPLICE_READ	Indicates that libfuse should try to use splice() when reading from the fuse device.
static final int	FUSE_CAP_SPLICE_WRITE	Indicates that libfuse should try to use splice() when writing to the fuse device.
static final int	FUSE_CAP_WRITEBACK_CACHE	Indicates that writeback caching should be enabled.

Method Summary

Modifier and Type	Method	Description
default int	asyncRead()	Is asynchronous read supported (read-write).
int	capable()	Capability flags that the kernel supports (read-only)
int	congestionThreshold()	Kernel congestion threshold parameter.
int	maxBackground()	Maximum number of pending "background" requests.
default int	maxRead()	Maximum size of read requests.
int	maxReadahead()	Maximum readahead.
int	maxWrite()	Maximum size of the write buffer.
int	protoMajor()	Major version of the protocol (read-only)
int	protoMinor()	Minor version of the protocol (read-only)
default void	setAsyncRead(int asyncRead)	Sets the asyncRead() value.
void	setCongestionThreshold(int congestionThreshold)	Sets the congestionThreshold() value.
void	setMaxBackground(int maxBackground)	Sets the maxBackground() value.
default void	setMaxRead(int maxRead)	Sets the maxRead() value.
void	setMaxReadahead(int maxReadahead)	Sets the maxReadahead() value.
void	setMaxWrite(int maxWrite)	Sets the maxWrite() value.
default void	setTimeGran(int timeGran)	Sets the timeGran() value.
void	setWant(int wanted)	Sets the want() value.
default int	timeGran()	When FUSE_CAP_WRITEBACK_CACHE is enabled, the kernel is responsible for updating mtime and ctime when write requests are received.
int	want()	Capability flags that the filesystem wants to enable.

Field Details

FUSE_CAP_ASYNC_READ

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_POSIX_LOCKS

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_ATOMIC_O_TRUNC

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_EXPORT_SUPPORT

static final int FUSE_CAP_EXPORT_SUPPORT

Indicates that the filesystem supports lookups of "." and "..".

This feature is disabled by default.

See Also:

• Constant Field Values

FUSE_CAP_BIG_WRITES

static final int FUSE_CAP_BIG_WRITES

Indicates that the filesystem can handle write size larger than 4kB

libFUSE 2.x only

See Also:

• Constant Field Values

FUSE_CAP_DONT_MASK

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_SPLICE_WRITE

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_SPLICE_MOVE

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_SPLICE_READ

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_FLOCK_LOCKS

static final int 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.

See Also:

• Constant Field Values

FUSE_CAP_IOCTL_DIR

static final int FUSE_CAP_IOCTL_DIR

Indicates that the filesystem supports ioctl's on directories.

This feature is enabled by default when supported by the kernel.

See Also:

• Constant Field Values

FUSE_CAP_AUTO_INVAL_DATA

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_READDIRPLUS

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_READDIRPLUS_AUTO

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_ASYNC_DIO

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_WRITEBACK_CACHE

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_NO_OPEN_SUPPORT

static final int 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 (or unsetting) this flag in the `want` field has *no effect*.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_PARALLEL_DIROPS

static final int 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.

This feature is enabled by default when supported by the kernel.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_POSIX_ACL

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_HANDLE_KILLPRIV

static final int 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 enabled by default when supported by the kernel.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_CACHE_SYMLINKS

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_NO_OPENDIR_SUPPORT

static final int 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 (or unsetting) this flag in the `want` field has *no effect*.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

FUSE_CAP_EXPLICIT_INVAL_DATA

static final int 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.

Since:

libFUSE 3.0

See Also:

• Constant Field Values

Method Details

protoMajor

int protoMajor()

Major version of the protocol (read-only)

Returns:

proto_major value

protoMinor

int protoMinor()

Minor version of the protocol (read-only)

Returns:

proto_minor value

capable

int capable()

Capability flags that the kernel supports (read-only)

Returns:

capable value

want

int want()

Capability flags that the filesystem wants to enable.

libfuse attempts to initialize this field with reasonable default values before calling the init() handler.

Returns:

want value

setWant

void setWant(int wanted)

Sets the want() value.

Parameters:

wanted - want value

maxWrite

int maxWrite()

Maximum size of the write buffer.

Returns:

max_write buffer

setMaxWrite

void setMaxWrite(int maxWrite)

Sets the maxWrite() value.

Parameters:

maxWrite - max_write value

maxRead

default int maxRead()

Maximum size of read requests. A value of zero indicates no limit. However, even if the filesystem does not specify a limit, the maximum size of read requests will still be limited by the kernel.

NOTE: For the time being, the maximum size of read requests must be set both here *and* passed to fuse_session_new() using the -o max_read=<n> mount option. At some point in the future, specifying the mount option will no longer be necessary.

Returns:

max_read value or 0 if not supported

Since:

libFUSE 3.0

setMaxRead

default void setMaxRead(int maxRead)

Sets the maxRead() value.

Parameters:

maxRead - max_read value

Since:

libFUSE 3.0

maxReadahead

int maxReadahead()

Maximum readahead.

Returns:

max_readahead value

setMaxReadahead

void setMaxReadahead(int maxReadahead)

Sets the maxReadahead() value.

Parameters:

maxReadahead - max_readahead value

maxBackground

int maxBackground()

Maximum number of pending "background" requests. A background request is any type of request for which the total number is not limited by other means. As of kernel 4.8, only two types of requests fall into this category:

1. Read-ahead requests
2. Asynchronous direct I/O requests

Read-ahead requests are generated (if max_readahead is non-zero) by the kernel to preemptively fill its caches when it anticipates that userspace will soon read more data.

Asynchronous direct I/O requests are generated if FUSE_CAP_ASYNC_DIO is enabled and userspace submits a large direct I/O request. In this case the kernel will internally split it up into multiple smaller requests and submit them to the filesystem concurrently.

Note that the following requests are *not* background requests: writeback requests (limited by the kernel's flusher algorithm), regular (i.e., synchronous and buffered) userspace read/write requests (limited to one per thread), asynchronous read requests (Linux's io_submit(2) call actually blocks, so these are also limited to one per thread).

Returns:

max_background value

setMaxBackground

void setMaxBackground(int maxBackground)

Sets the maxBackground() value.

Parameters:

maxBackground - max_background value

congestionThreshold

int congestionThreshold()

Kernel congestion threshold parameter. If the number of pending background requests exceeds this number, the FUSE kernel module will mark the filesystem as "congested". This instructs the kernel to expect that queued requests will take some time to complete, and to adjust its algorithms accordingly (e.g. by putting a waiting thread to sleep instead of using a busy-loop).

Returns:

congestion_threshold value

setCongestionThreshold

void setCongestionThreshold(int congestionThreshold)

Sets the congestionThreshold() value.

Parameters:

congestionThreshold - congestion_threshold value

timeGran

default int timeGran()

When FUSE_CAP_WRITEBACK_CACHE is enabled, the kernel is responsible for updating mtime and ctime when write requests are received. The updated values are passed to the filesystem with setattr() requests. However, if the filesystem does not support the full resolution of the kernel timestamps (nanoseconds), the mtime and ctime values used by kernel and filesystem will differ (and result in an apparent change of times after a cache flush).

To prevent this problem, this variable can be used to inform the kernel about the timestamp granularity supported by the file-system. The value should be power of 10. The default is 1, i.e. full nano-second resolution. Filesystems supporting only second resolution should set this to 1000000000.

Returns:

time_gran value or 0 if not supported

Since:

libFUSE 3.0

setTimeGran

default void setTimeGran(int timeGran)

Sets the timeGran() value.

Parameters:

timeGran - time_gran value

Since:

libFUSE 3.0

asyncRead

default int asyncRead()

Is asynchronous read supported (read-write).

Returns:

async_read value or 0 if not supported

setAsyncRead

default void setAsyncRead(int asyncRead)

Sets the asyncRead() value.

Parameters:

asyncRead - async_read value