Module org.cryptomator.jfuse.api

Package org.cryptomator.jfuse.api

Interface FuseOperations

All Known Subinterfaces:

FuseOperationsDecorator

public interface FuseOperations

The file system operations.

See Also:

• fuse_operations

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	FuseOperations.Operation

Field Summary

Fields

Modifier and Type	Field	Description
static final int	FUSE_READDIR_PLUS	"Plus" mode.

Method Summary

Modifier and Type	Method	Description
default int	access(String path, int mask)	Check file access permissions.
default int	chmod(String path, int mode, @Nullable FileInfo fi)	Change the permission bits of a file
default int	chown(String path, int uid, int gid, @Nullable FileInfo fi)	Change the owner and group of a file
default int	create(String path, int mode, FileInfo fi)	Create and open a file.
default void	destroy()	Clean up filesystem
Errno	errno()	The error constants used by this file system.
default int	fallocate(String path, int mode, long offset, long length, FileInfo fi)	Allocates space for an open file.
default int	flock(String path, FileInfo fi, int op)	Perform BSD file locking operation.
default int	flush(String path, FileInfo fi)	Possibly flush cached data.
default int	fsync(String path, int datasync, FileInfo fi)	Synchronize file contents
default int	fsyncdir(@Nullable String path, int datasync, FileInfo fi)	Synchronize directory contents
default int	getattr(String path, Stat stat, @Nullable FileInfo fi)	Get file attributes.
default int	getxattr(String path, String name, ByteBuffer value)	Get extended attributes
default void	init(FuseConnInfo conn, @Nullable FuseConfig cfg)	Initialize filesystem
default int	ioctl(String path, int cmd, ByteBuffer arg, FileInfo fi, int flags, @Nullable ByteBuffer data)	Ioctl
default int	link(String linkname, String target)	Create a hard link to a file
default int	listxattr(String path, ByteBuffer list)	List extended attributes
default int	mkdir(String path, int mode)	Create a directory.
default int	mknod(String path, short mode, int rdev)	Create a file node.
default int	open(String path, FileInfo fi)	Open a file.
default int	opendir(String path, FileInfo fi)	Open directory.
default int	read(String path, ByteBuffer buf, long count, long offset, FileInfo fi)	Read data from an open file.
default int	readdir(String path, DirFiller filler, long offset, FileInfo fi, int flags)	Read directory.
default int	readlink(String path, ByteBuffer buf, long len)	Read the target of a symbolic link.
default int	release(String path, FileInfo fi)	Release an open file.
default int	releasedir(@Nullable String path, FileInfo fi)	Release directory
default int	removexattr(String path, String name)	Remove extended attributes
default int	rename(String oldpath, String newpath, int flags)	Rename a file
default int	rmdir(String path)	Remove a directory
default int	setxattr(String path, String name, ByteBuffer value, int flags)	Set extended attributes
default int	statfs(String path, Statvfs statvfs)	Get file system statistics.
Set<FuseOperations.Operation>	supportedOperations()	The supported file system operations.
default int	symlink(String linkname, String target)	Create a symbolic link
default int	truncate(String path, long size, @Nullable FileInfo fi)	Change the size of a file.
default int	unlink(String path)	Remove a file
default int	utimens(String path, TimeSpec atime, TimeSpec mtime, @Nullable FileInfo fi)	Change the access and modification times of a file with nanosecond resolution.
default int	write(String path, ByteBuffer buf, long count, long offset, FileInfo fi)	Write data to an open file.

Field Details

FUSE_READDIR_PLUS

static final int FUSE_READDIR_PLUS

"Plus" mode.

The kernel wants to prefill the inode cache during readdir. The filesystem may honour this by filling in the attributes and setting FUSE_FILL_DIR_PLUS for the filler function. The filesystem may also just ignore this flag completely.

See Also:

• Constant Field Values

Method Details

errno

Errno errno()

The error constants used by this file system.

Returns:

The error codes from errno.h for the current platform.

See Also:

• FuseBuilder.errno()

supportedOperations

Set<FuseOperations.Operation> supportedOperations()

The supported file system operations.

Returns:

The set of supported operations.

getattr

default int getattr(String path,
 Stat stat,
 @Nullable
 @Nullable FileInfo fi)

Get file attributes.

Similar to stat(). The 'st_dev' and 'st_blksize' fields are ignored. The 'st_ino' field is ignored except if the 'use_ino' mount option is given. In that case it is passed to userspace, but libfuse and the kernel will still assign a different inode for internal use (called the "nodeid").

This method doubles as fgetattr in libfuse2

Parameters:

path - file path

stat - file information

fi - will always be null if the file is not currently open, but may also be null if the file is open.

Returns:

0 on success or negated error code (-errno)

readlink

default int readlink(String path,
 ByteBuffer buf,
 long len)

Read the target of a symbolic link.

Parameters:

path - file path

buf - The buffer should be filled with a null terminated string.

len - The buffer size (including the terminating null character). If the linkname is too long to fit in the buffer, it should be truncated.

Returns:

The return value should be 0

mknod

default int mknod(String path,
 short mode,
 int rdev)

Create a file node.

This is called for creation of all non-directory, non-symlink nodes. If the filesystem defines a create() method, then for regular files that will be called instead.

Parameters:

path - file path

mode - file mode and type of node to create (using bitwise OR)

rdev - ignored if mode does not contain S_IFCHR or S_IFBLK

Returns:

0 on success or negated error code (-errno)

mkdir

default int mkdir(String path,
 int mode)

Create a directory.

Note that the mode argument may not have the type specification bits set, i.e. S_ISDIR(mode) can be false. To obtain the correct directory type bits use mode|S_IFDIR

Parameters:

path - file path

mode - file mode (using bitwise OR)

Returns:

0 on success or negated error code (-errno)

unlink

default int unlink(String path)

Remove a file

Parameters:

path - file path

Returns:

0 on success or negated error code (-errno)

rmdir

default int rmdir(String path)

Remove a directory

Parameters:

path - file path

Returns:

0 on success or negated error code (-errno)

symlink

default int symlink(String linkname,
 String target)

Create a symbolic link

Parameters:

linkname - file path

target - content of the link

Returns:

0 on success or negated error code (-errno)

rename

default int rename(String oldpath,
 String newpath,
 int flags)

Rename a file

Parameters:

oldpath - old file path

newpath - new file path

flags - may be `RENAME_EXCHANGE` or `RENAME_NOREPLACE`. If RENAME_NOREPLACE is specified, the filesystem must not overwrite *newname* if it exists and return an error instead. If `RENAME_EXCHANGE` is specified, the filesystem must atomically exchange the two files, i.e. both must exist and neither may be deleted.

Returns:

0 on success or negated error code (-errno)

link

default int link(String linkname,
 String target)

Create a hard link to a file

Parameters:

linkname - file path

target - content of the link

Returns:

0 on success or negated error code (-errno)

chmod

default int chmod(String path,
 int mode,
 @Nullable
 @Nullable FileInfo fi)

Change the permission bits of a file

Parameters:

path - file path

mode - file mode (using bitwise OR)

fi - will always be null if the file is not currently open, but may also be null if the file is open.

Returns:

0 on success or negated error code (-errno)

chown

default int chown(String path,
 int uid,
 int gid,
 @Nullable
 @Nullable FileInfo fi)

Change the owner and group of a file

Parameters:

path - file path

uid - user id

gid - group id

fi - will always be null if the file is not currently open, but may also be null if the file is open.

Returns:

0 on success or negated error code (-errno)

truncate

default int truncate(String path,
 long size,
 @Nullable
 @Nullable FileInfo fi)

Change the size of a file.

Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is expected to reset the setuid and setgid bits.

This method doubles as ftruncate in libfuse2

Parameters:

path - file path

size - new size of the file

fi - will always be null if the file is not currently open, but may also be null if the file is open.

Returns:

0 on success or negated error code (-errno)

open

default int open(String path,
 FileInfo fi)

Open a file.

Open flags are available in fi->flags. The following rules apply.

• Creation (O_CREAT, O_EXCL, O_NOCTTY) flags will be filtered out / handled by the kernel.
• Access modes (O_RDONLY, O_WRONLY, O_RDWR, O_EXEC, O_SEARCH) should be used by the filesystem to check if the operation is permitted. If the ``-o default_permissions`` mount option is given, this check is already done by the kernel before calling open() and may thus be omitted by the filesystem.
• When writeback caching is enabled, the kernel may send read requests even for files opened with O_WRONLY. Thefilesystem should be prepared to handle this.
• When writeback caching is disabled, the filesystem is expected to properly handle the O_APPEND flag and ensurethat each write is appending to the end of the file.
• When writeback caching is enabled, the kernel will handle O_APPEND. However, unless all changes to the file come through the kernel this will not work reliably. The filesystem should thus either ignore the O_APPEND flag (and let the kernel handle it), or return an error (indicating that reliably O_APPEND is not available).

Filesystem may store an arbitrary file handle (pointer, index, etc) in fi->fh, and use this in other all other file operations (read, write, flush, release, fsync).

Filesystem may also implement stateless file I/O and not store anything in fi->fh.

There are also some flags (direct_io, keep_cache) which the filesystem may set in fi, to change the way the file is opened. See fuse_file_info structure in fuse_common.h for more details.

If this request is answered with an error code of ENOSYS and FUSE_CAP_NO_OPEN_SUPPORT is set in `fuse_conn_info.capable`, this is treated as success and future calls to open will also succeed without being send to the filesystem process.

Parameters:

path - file path

fi - file info, which may be used to store a file handle

Returns:

0 on success or negated error code (-errno)

read

default int read(String path,
 ByteBuffer buf,
 long count,
 long offset,
 FileInfo fi)

Read data from an open file.

Read should return exactly the number of bytes requested except on EOF or error, otherwise the rest of the data will be substituted with zeroes. An exception to this is when the 'direct_io' mount option is specified, in which case the return value of the read system call will reflect the return value of this operation.

Parameters:

path - file path

buf - the buffer to read into

count - number of bytes to read

offset - position in the file to start reading

fi - file info

Returns:

number of bytes read or negated error code (-errno)

write

default int write(String path,
 ByteBuffer buf,
 long count,
 long offset,
 FileInfo fi)

Write data to an open file.

Write should return exactly the number of bytes requested except on error. An exception to this is when the 'direct_io' mount option is specified (see read operation).

Unless FUSE_CAP_HANDLE_KILLPRIV is disabled, this method is expected to reset the setuid and setgid bits.

Parameters:

path - file path

buf - the buffer containing the data to be written

count - number of bytes to write

offset - position in the file to write to

fi - file info

Returns:

number of bytes written or negated error code (-errno)

statfs

default int statfs(String path,
 Statvfs statvfs)

Get file system statistics.

The 'f_favail', 'f_fsid' and 'f_flag' fields are ignored

Parameters:

path - file path of any file within the file system

statvfs - The statistics object to be filled with data

Returns:

0 on success or negated error code (-errno)

flush

default int flush(String path,
 FileInfo fi)

Possibly flush cached data.

BIG NOTE: This is not equivalent to fsync(). It's not a request to sync dirty data.

Flush is called on each close() of a file descriptor, as opposed to release which is called on the close of the last file descriptor for a file. Under Linux, errors returned by flush() will be passed to userspace as errors from close(), so flush() is a good place to write back any cached dirty data. However, many applications ignore errors on close(), and on non-Linux systems, close() may succeed even if flush() returns an error. For these reasons, filesystems should not assume that errors returned by flush will ever be noticed or even delivered.

NOTE: The flush() method may be called more than once for each open(). This happens if more than one file descriptor refers to an open file handle, e.g. due to dup(), dup2() or fork() calls. It is not possible to determine if a flush is final, so each flush should be treated equally. Multiple write-flush sequences are relatively rare, so this shouldn't be a problem.

Filesystems shouldn't assume that flush will be called at any particular point. It may be called more times than expected, or not at all.

Parameters:

path - file path

fi - file info

Returns:

0 on success or negated error code (-errno)

release

default int release(String path,
 FileInfo fi)

Release an open file.

Release is called when there are no more references to an open file: all file descriptors are closed and all memory mappings are unmapped.

For every open() call there will be exactly one release() call with the same flags and file handle. It is possible to have a file opened more than once, in which case only the last release will mean, that no more reads/writes will happen on the file. The return value of release is ignored.

Parameters:

path - file path

fi - file info

Returns:

0 on success or negated error code (-errno)

fsync

default int fsync(String path,
 int datasync,
 FileInfo fi)

Synchronize file contents

Parameters:

path - file path

datasync - if non-zero, then only the user data should be flushed, not the meta data.

fi - file info

Returns:

0 on success or negated error code (-errno)

setxattr

default int setxattr(String path,
 String name,
 ByteBuffer value,
 int flags)

Set extended attributes

Parameters:

path - file path

name - attribute name

value - attribute value

flags - defaults to zero, which creates or replaces the attribute. For fine-grained atomic control, XATTR_CREATE or XATTR_REPLACE may be used.

Returns:

0 on success or negated error code (-errno)

getxattr

default int getxattr(String path,
 String name,
 ByteBuffer value)

Get extended attributes

Parameters:

path - file path

name - attribute name

value - attribute value. If buffer capacity is zero, return the size of the value

Returns:

the non-negative value size or negated error code (-errno)

listxattr

default int listxattr(String path,
 ByteBuffer list)

List extended attributes

Parameters:

path - file path

list - consecutive list of null-terminated attribute names (as many as fit into the buffer). If buffer capacity is zero, return the size of the list

Returns:

the non-negative number of bytes written to the list buffer or negated error code (-errno)

removexattr

default int removexattr(String path,
 String name)

Remove extended attributes

Parameters:

path - file path

name - attribute name

Returns:

0 on success or negated error code (-errno)

opendir

default int opendir(String path,
 FileInfo fi)

Open directory.

Unless the 'default_permissions' mount option is given, this method should check if opendir is permitted for this directory. Optionally opendir may also return an arbitrary filehandle in the fuse_file_info structure, which will be passed to readdir, releasedir and fsyncdir.

Parameters:

path - directory path

fi - file info, which may be used to store a file handle

Returns:

0 on success or negated error code (-errno)

readdir

default int readdir(String path,
 DirFiller filler,
 long offset,
 FileInfo fi,
 int flags)

Read directory.

The filesystem may choose between two modes of operation:

1. The readdir implementation ignores the offset parameter, and passes zero to the filler function's offset. The filler function will not return '1' (unless an error happens), so the whole directory is read in a single readdir operation.
2. The readdir implementation keeps track of the offsets of the directory entries. It uses the offset parameter and always passes non-zero offset to the filler function. When the buffer is full (or an error happens) the filler function will return '1'.

Parameters:

path - directory path

filler - the fill function

offset - the offset

fi - file info

flags - When FUSE_READDIR_PLUS is not set, only some parameters of the fill function (the filler parameter) are actually used: The file type (which is part of Stat.getMode()) is used. And if fuse_config::use_ino is set, the inode (stat::st_ino) is also used. The other fields are ignored when READ_DIR_PLUS is not set.

Returns:

0 on success or negated error code (-errno)

releasedir

default int releasedir(@Nullable
 @Nullable String path,
 FileInfo fi)

Release directory

Parameters:

path - directory path. If the directory has been removed after the call to opendir, the path parameter will be null

fi - file info

Returns:

0 on success or negated error code (-errno)

fsyncdir

default int fsyncdir(@Nullable
 @Nullable String path,
 int datasync,
 FileInfo fi)

Synchronize directory contents

Parameters:

path - directory path. If the directory has been removed after the call to opendir, the path parameter will be null

datasync - if non-zero, then only the user data should be flushed, not the meta data

fi - file info

Returns:

0 on success or negated error code (-errno)

init

default void init(FuseConnInfo conn,
 @Nullable
 @Nullable FuseConfig cfg)

Initialize filesystem

Parameters:

conn - FUSE connection information

cfg - FUSE configuration object

destroy

default void destroy()

Clean up filesystem

Called on filesystem exit.

access

default int access(String path,
 int mask)

Check file access permissions.

This will be called for the access() system call. If the 'default_permissions' mount option is given, this method is not called.

This method is not called under Linux kernel versions 2.4.x

Parameters:

path - file path

mask - bitwise OR of file access checks

Returns:

0 on success or negated error code (-errno)

create

default int create(String path,
 int mode,
 FileInfo fi)

Create and open a file.

If the file does not exist, first create it with the specified mode, and then open it.

If this method is not implemented or under Linux kernel versions earlier than 2.6.15, the mknod() and open() methods will be called instead.

Parameters:

path - file path

mode - mode used to create the file if it does not exist yet

fi - file info, which may be used to store a file handle

Returns:

0 on success or negated error code (-errno)

utimens

default int utimens(String path,
 TimeSpec atime,
 TimeSpec mtime,
 @Nullable
 @Nullable FileInfo fi)

Change the access and modification times of a file with nanosecond resolution.

This supersedes the old utime() interface. New applications should use this.

See the utimensat(2) man page for details.

Parameters:

path - file path

atime - last access time

mtime - last modified time

fi - will always be null if the file is not currently open, but may also be null if the file is open.

Returns:

0 on success or negated error code (-errno)

ioctl

default int ioctl(String path,
 int cmd,
 ByteBuffer arg,
 FileInfo fi,
 int flags,
 @Nullable
 @Nullable ByteBuffer data)

Ioctl

flags will have FUSE_IOCTL_COMPAT set for 32bit ioctls in 64bit environment. The size and direction of data is determined by _IOC_*() decoding of cmd. For _IOC_NONE, data will be NULL, for _IOC_WRITE data is out area, for _IOC_READ in area and if both are set in/out area. In all non-NULL cases, the area is of _IOC_SIZE(cmd) bytes.

Note: the unsigned long request submitted by the application is truncated to 32 bits.

Parameters:

path - file path

cmd - the request

arg - any arguments

fi - file info

flags - if containing FUSE_IOCTL_DIR then the fi refers to a directory file handle.

data - data (depends on cmd and may be null)

Returns:

0 on success or negated error code (-errno)

flock

default int flock(String path,
 FileInfo fi,
 int op)

Perform BSD file locking operation.

The op argument will be either LOCK_SH, LOCK_EX or LOCK_UN

Nonblocking requests will be indicated by ORing LOCK_NB to the above operations

For more information see the flock(2) manual page.

Additionally fi->owner will be set to a value unique to this open file. This same value will be supplied to ->release() when the file is released.

Note: if this method is not implemented, the kernel will still allow file locking to work locally. Hence it is only interesting for network filesystems and similar.

Parameters:

path - file path

fi - file info

op - one of LOCK_SH, LOCK_EX or LOCK_UN

Returns:

0 on success or negated error code (-errno)

fallocate

default int fallocate(String path,
 int mode,
 long offset,
 long length,
 FileInfo fi)

Allocates space for an open file.

This function ensures that required space is allocated for specified file. If this function returns success then any subsequent write request to specified range is guaranteed not to fail because of lack of space on the file system media.

Parameters:

path - file path

mode - the operation to be performed

offset - start of the allocated region

length - number of bytes to allocate in this file

fi - file info

Returns:

0 on success or negated error code (-errno)