Struct fuse3_opendal::Filesystem

pub struct Filesystem { /* private fields */ }

Filesystem represents the filesystem that implements [PathFilesystem] by opendal.

Filesystem must be used along with fuse3’s Session like the following:

use fuse3::path::Session;
use fuse3::MountOptions;
use fuse3::Result;
use fuse3_opendal::Filesystem;
use opendal::services::Memory;
use opendal::Operator;

#[tokio::test]
async fn test() -> Result<()> {
    // Build opendal Operator.
    let op = Operator::new(Memory::default())?.finish();

    // Build fuse3 file system.
    let fs = Filesystem::new(op, 1000, 1000);

    // Configure mount options.
    let mount_options = MountOptions::default();

    // Start a fuse3 session and mount it.
    let mut mount_handle = Session::new(mount_options)
        .mount_with_unprivileged(fs, "/tmp/mount_test")
        .await?;
    let handle = &mut mount_handle;

    tokio::select! {
        res = handle => res?,
        _ = tokio::signal::ctrl_c() => {
            mount_handle.unmount().await?
        }
    }

    Ok(())
}

Implementations

impl Filesystem

pub fn new(op: Operator, uid: u32, gid: u32) -> Self

Create a new filesystem with given operator, uid and gid.

Trait Implementations

impl PathFilesystem for Filesystem

async fn flush( &self, _req: Request, path: Option<&OsStr>, fh: u64, lock_owner: u64, ) -> Result<()>

In design, flush could be called multiple times for a single open. But there is the only place that we can handle the write operations.

So we only support the use case that flush only be called once.

async fn init(&self, _req: Request) -> Result<ReplyInit>

initialize filesystem. Called before any other filesystem method.

async fn destroy(&self, _req: Request)

clean up filesystem. Called on filesystem exit which is fuseblk, in normal fuse filesystem, kernel may call forget for root. There is some discuss for this https://github.com/bazil/fuse/issues/82#issuecomment-88126886, https://sourceforge.net/p/fuse/mailman/message/31995737/

async fn lookup( &self, _req: Request, parent: &OsStr, name: &OsStr, ) -> Result<ReplyEntry>

look up a directory entry by name and get its attributes.

async fn getattr( &self, _req: Request, path: Option<&OsStr>, fh: Option<u64>, flags: u32, ) -> Result<ReplyAttr>

get file attributes. If fh is None, means fh is not set. If path is None, means the path may be deleted.

async fn setattr( &self, _req: Request, path: Option<&OsStr>, fh: Option<u64>, set_attr: SetAttr, ) -> Result<ReplyAttr>

set file attributes. If fh is None, means fh is not set. If path is None, means the path may be deleted.

async fn symlink( &self, _req: Request, parent: &OsStr, name: &OsStr, link_path: &OsStr, ) -> Result<ReplyEntry>

create a symbolic link.

async fn mknod( &self, _req: Request, parent: &OsStr, name: &OsStr, mode: u32, _rdev: u32, ) -> Result<ReplyEntry>

create file node. Create a regular file, character device, block device, fifo or socket node. When creating file, most cases user only need to implement [create][PathFilesystem::create].

async fn mkdir( &self, _req: Request, parent: &OsStr, name: &OsStr, mode: u32, _umask: u32, ) -> Result<ReplyEntry>

create a directory.

async fn unlink( &self, _req: Request, parent: &OsStr, name: &OsStr, ) -> Result<()>

remove a file.

async fn rmdir(&self, _req: Request, parent: &OsStr, name: &OsStr) -> Result<()>

remove a directory.

async fn rename( &self, _req: Request, origin_parent: &OsStr, origin_name: &OsStr, parent: &OsStr, name: &OsStr, ) -> Result<()>

rename a file or directory.

async fn link( &self, _req: Request, path: &OsStr, new_parent: &OsStr, new_name: &OsStr, ) -> Result<ReplyEntry>

create a hard link.

async fn opendir( &self, _req: Request, path: &OsStr, flags: u32, ) -> Result<ReplyOpen>

open a directory. Filesystem may store an arbitrary file handle (pointer, index, etc) in fh, and use this in other all other directory stream operations ([readdir][PathFilesystem::readdir], [releasedir][PathFilesystem::releasedir], [fsyncdir][PathFilesystem::fsyncdir]). Filesystem may also implement stateless directory I/O and not store anything in fh. A file system need not implement this method if it sets [MountOptions::no_open_dir_support][crate::MountOptions::no_open_dir_support] and if the kernel supports FUSE_NO_OPENDIR_SUPPORT.

async fn open( &self, _req: Request, path: &OsStr, flags: u32, ) -> Result<ReplyOpen>

open a file. Open flags (with the exception of O_CREAT, O_EXCL and O_NOCTTY) are available in flags. Filesystem may store an arbitrary file handle (pointer, index, etc) in 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 fh. There are also some flags (direct_io, keep_cache) which the filesystem may set, to change the way the file is opened. A file system need not implement this method if it sets [MountOptions::no_open_support][crate::MountOptions::no_open_support] and if the kernel supports FUSE_NO_OPEN_SUPPORT.

async fn read( &self, _req: Request, path: Option<&OsStr>, fh: u64, offset: u64, size: u32, ) -> Result<ReplyData>

read data. Read should send 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 file has been opened in direct_io mode, in which case the return value of the read system call will reflect the return value of this operation. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value. when path is None, it means the path may be deleted.

async fn write( &self, _req: Request, path: Option<&OsStr>, fh: u64, offset: u64, data: &[u8], _write_flags: u32, flags: u32, ) -> Result<ReplyWrite>

write data. Write should return exactly the number of bytes requested except on error. An exception to this is when the file has been opened in direct_io mode, in which case the return value of the write system call will reflect the return value of this operation. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value. When path is None, it means the path may be deleted. When write_flags contains FUSE_WRITE_CACHE, means the write operation is a delay write.

async fn release( &self, _req: Request, path: Option<&OsStr>, fh: u64, flags: u32, lock_owner: u64, flush: bool, ) -> Result<()>

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. The filesystem may reply with an error, but error values are not returned to close() or munmap() which triggered the release. fh will contain the value set by the open method, or will be undefined if the open method didn’t set any value. flags will contain the same flags as for open. flush means flush the data or not when closing file. when path is None, it means the path may be deleted.

type DirEntryStream<'a> = Pin<Box<dyn Stream<Item = Result<DirectoryEntry, Errno>> + Send + 'a>>

dir entry stream given by [readdir][PathFilesystem::readdir].

async fn readdir<'a>( &'a self, _req: Request, path: &'a OsStr, fh: u64, offset: i64, ) -> Result<ReplyDirectory<Self::DirEntryStream<'a>>>

read directory. offset is used to track the offset of the directory entries. fh will contain the value set by the [opendir][PathFilesystem::opendir] method, or will be undefined if the [opendir][PathFilesystem::opendir] method didn’t set any value.

async fn access(&self, _req: Request, path: &OsStr, mask: u32) -> Result<()>

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 be called. This method is not called under Linux kernel versions 2.4.x.

async fn create( &self, _req: Request, parent: &OsStr, name: &OsStr, mode: u32, flags: u32, ) -> Result<ReplyCreated>

create and open a file. If the file does not exist, first create it with the specified mode, and then open it. Open flags (with the exception of O_NOCTTY) are available in flags. Filesystem may store an arbitrary file handle (pointer, index, etc) in fh, and use this in other all other file operations ([read][PathFilesystem::read], [write][PathFilesystem::write], [flush][PathFilesystem::flush], [release][PathFilesystem::release], [fsync][PathFilesystem::fsync]). There are also some flags (direct_io, keep_cache) which the filesystem may set, to change the way the file is opened. If this method is not implemented or under Linux kernel versions earlier than 2.6.15, the [mknod][PathFilesystem::mknod] and [open][PathFilesystem::open] methods will be called instead.

type DirEntryPlusStream<'a> = Pin<Box<dyn Stream<Item = Result<DirectoryEntryPlus, Errno>> + Send + 'a>>

dir entry plus stream given by [readdirplus][PathFilesystem::readdirplus].

async fn readdirplus<'a>( &'a self, _req: Request, parent: &'a OsStr, fh: u64, offset: u64, _lock_owner: u64, ) -> Result<ReplyDirectoryPlus<Self::DirEntryPlusStream<'a>>>

read directory entries, but with their attribute, like [readdir][PathFilesystem::readdir]

async fn rename2( &self, req: Request, origin_parent: &OsStr, origin_name: &OsStr, parent: &OsStr, name: &OsStr, _flags: u32, ) -> Result<()>

rename a file or directory with flags.

async fn copy_file_range( &self, req: Request, from_path: Option<&OsStr>, fh_in: u64, offset_in: u64, to_path: Option<&OsStr>, fh_out: u64, offset_out: u64, length: u64, flags: u64, ) -> Result<ReplyCopyFileRange>

copy a range of data from one file to another. This can improve performance because it reduce data copy: in normal, data will copy from FUSE server to kernel, then to user-space, then to kernel, finally send back to FUSE server. By implement this method, data will only copy in FUSE server internal. when from_path or to_path is None, it means the path may be deleted.

async fn statfs(&self, _req: Request, path: &OsStr) -> Result<ReplyStatFs>

get filesystem statistics.

fn forget( &self, req: Request, parent: &OsStr, nlookup: u64, ) -> impl Future<Output = ()> + Send

forget an path. The nlookup parameter indicates the number of lookups previously performed on this path. If the filesystem implements path lifetimes, it is recommended that paths acquire a single reference on each lookup, and lose nlookup references on each forget. The filesystem may ignore forget calls, if the paths don’t need to have a limited lifetime. On unmount it is not guaranteed, that all referenced paths will receive a forget message. When filesystem is normal(not fuseblk) and unmounting, kernel may send forget request for root and this library will stop session after call forget. There is some discussion for this https://github.com/bazil/fuse/issues/82#issuecomment-88126886, https://sourceforge.net/p/fuse/mailman/message/31995737/ https://sourceforge.net/p/fuse/mailman/message/31995737/

fn readlink( &self, req: Request, path: &OsStr, ) -> impl Future<Output = Result<ReplyData, Errno>> + Send

read symbolic link.

fn fsync( &self, req: Request, path: Option<&OsStr>, fh: u64, datasync: bool, ) -> impl Future<Output = Result<(), Errno>> + Send

synchronize file contents. If the datasync is true, then only the user data should be flushed, not the metadata. when path is None, it means the path may be deleted.

fn setxattr( &self, req: Request, path: &OsStr, name: &OsStr, value: &[u8], flags: u32, position: u32, ) -> impl Future<Output = Result<(), Errno>> + Send

set an extended attribute.

fn getxattr( &self, req: Request, path: &OsStr, name: &OsStr, size: u32, ) -> impl Future<Output = Result<ReplyXAttr, Errno>> + Send

get an extended attribute. If size is too small, use [ReplyXAttr::Size] to return correct size. If size is enough, use [ReplyXAttr::Data] to send it, or return error.

fn listxattr( &self, req: Request, path: &OsStr, size: u32, ) -> impl Future<Output = Result<ReplyXAttr, Errno>> + Send

list extended attribute names. If size is too small, use [ReplyXAttr::Size] to return correct size. If size is enough, use [ReplyXAttr::Data] to send it, or return error.

fn removexattr( &self, req: Request, path: &OsStr, name: &OsStr, ) -> impl Future<Output = Result<(), Errno>> + Send

remove an extended attribute.

fn releasedir( &self, req: Request, path: &OsStr, fh: u64, flags: u32, ) -> impl Future<Output = Result<(), Errno>> + Send

release an open directory. For every [opendir][PathFilesystem::opendir] call there will be exactly one releasedir call. fh will contain the value set by the [opendir][PathFilesystem::opendir] method, or will be undefined if the [opendir][PathFilesystem::opendir] method didn’t set any value.

fn fsyncdir( &self, req: Request, path: &OsStr, fh: u64, datasync: bool, ) -> impl Future<Output = Result<(), Errno>> + Send

synchronize directory contents. If the datasync is true, then only the directory contents should be flushed, not the metadata. fh will contain the value set by the [opendir][PathFilesystem::opendir] method, or will be undefined if the [opendir][PathFilesystem::opendir] method didn’t set any value.

fn interrupt( &self, req: Request, unique: u64, ) -> impl Future<Output = Result<(), Errno>> + Send

handle interrupt. When a operation is interrupted, an interrupt request will send to fuse server with the unique id of the operation.

fn bmap( &self, req: Request, path: &OsStr, block_size: u32, idx: u64, ) -> impl Future<Output = Result<ReplyBmap, Errno>> + Send

map block index within file to block index within device.

fn poll( &self, req: Request, path: Option<&OsStr>, fh: u64, kn: Option<u64>, flags: u32, envents: u32, notify: &Notify, ) -> impl Future<Output = Result<ReplyPoll, Errno>> + Send

poll for IO readiness events.

fn notify_reply( &self, req: Request, path: &OsStr, offset: u64, data: Bytes, ) -> impl Future<Output = Result<(), Errno>> + Send

receive notify reply from kernel.

fn batch_forget( &self, req: Request, paths: &[&OsStr], ) -> impl Future<Output = ()> + Send

forget more than one path. This is a batch version [forget][PathFilesystem::forget]

fn fallocate( &self, req: Request, path: Option<&OsStr>, fh: u64, offset: u64, length: u64, mode: u32, ) -> impl Future<Output = Result<(), Errno>> + Send

allocate space for an open file. This function ensures that required space is allocated for specified file.

fn lseek( &self, req: Request, path: Option<&OsStr>, fh: u64, offset: u64, whence: u32, ) -> impl Future<Output = Result<ReplyLSeek, Errno>> + Send

find next data or hole after the specified offset.