class

Fuse::FileSystem

Inherits Reference < Object

Base class for a FUSE filesystem. Subclass it and override the operations you care about; anything you leave alone returns a sensible default (-ENOENT for lookups, -ENOSYS for write operations on a read-only fs).

Reference it as Fuse::FileSystem, or via the short alias Fuse::FS.

Most operations come in two flavors: an ergonomic default that returns a Crystal value (FileAttr, Array(String), Bytes, …) and, where it matters, a lower-level "escape hatch" overload that hands you the raw buffer/pointer for zero-copy or full control. Override whichever you need; the escape-hatch forms delegate to the friendly ones by default. Any operation can also return a negative Errno value to signal failure, e.g. -Errno::ENOENT.value.

Instance methods

access(path : String, mask : Int32) : Int32

Check access permissions for path. Return 0 to allow.

bmap(path : String, blocksize : UInt64, idx : Pointer(UInt64)) : Int32

Map a logical file block to a device block (for block-backed filesystems). idx is in/out: the requested block in, the mapped block out.

chmod(path : String, mode : Int32) : Int32

Change the permission bits of path.

chown(path : String, uid : UInt32, gid : UInt32) : Int32

Change ownership of path.

copy_file_range(path_in : String, fi_in : FileInfo, offset_in : Int64, path_out : String, fi_out : FileInfo, offset_out : Int64, size : UInt64, flags : Int32) : Int64

Server-side copy of size bytes between two open files. Return the number of bytes copied, or a negative errno.

create(path : String, mode : Int32, fi : FileInfo) : Int32

Same as create but with the FileInfo (settable file handle).

create(path : String, mode : Int32) : Int32

Create and open a new file at path with the given mode.

destroy

Called once when the filesystem is unmounted.

fallocate(path : String, mode : Int32, offset : Int64, length : Int64, fi : FileInfo) : Int32

Preallocate or punch holes in a file's space (see fallocate(2) mode).

flock(path : String, fi : FileInfo, op : Int32) : Int32

BSD-style whole-file advisory lock (op is LOCK_SH / LOCK_EX / LOCK_UN …).

flush(path : String, fi : FileInfo) : Int32

Called on each close(2) of a descriptor (may fire more than once, or not at all). Return an error to surface it to close.

fsync(path : String, datasync : Bool, fi : FileInfo) : Int32

Sync a file's contents to storage. datasync true → flush data only.

fsyncdir(path : String, datasync : Bool, fi : FileInfo) : Int32

Sync a directory. datasync true → flush data only, not metadata.

getattr(path : String, stat : Pointer(LibC::Stat)) : Int32

Raw escape hatch: fill the kernel's struct stat (stat) directly and return 0, or a negative errno. Use this when you need a field FileAttr doesn't model. By default it calls the friendly FileAttr-returning form and marshals the result, so override one or the other.

getattr(path : String) : FileAttr | Int32

Attributes for the file at path (the stat(2) of FUSE).

getxattr(path : String, name : String) : Bytes | Int32

Return the value of extended attribute name, or a negative errno (e.g. -Errno::ENODATA.value when it doesn't exist).

init

Called once when the filesystem is mounted, before any other operation.

ioctl(path : String, cmd : UInt32, arg : Pointer(Void), fi : FileInfo, flags : UInt32, data : Pointer(Void)) : Int32

Device-style ioctl; arg/data are raw pointers per the ioctl protocol.

link(target : String, link_path : String) : Int32

Create a hard link at link_path referring to the existing file target.

listxattr(path : String) : Array(String) | Int32

Return the names of path's extended attributes.

lock(path : String, fi : FileInfo, cmd : Int32, lock : Pointer(LibC::Flock)) : Int32

POSIX (fcntl) advisory lock. cmd is F_GETLK / F_SETLK / F_SETLKW; lock points at a LibC::Flock to read and (for F_GETLK) write back.

lseek(path : String, offset : Int64, whence : Int32, fi : FileInfo) : Int64

Reposition the read/write offset; mainly SEEK_DATA/SEEK_HOLE for sparse files. Return the resulting offset, or a negative errno.

mkdir(path : String, mode : Int32) : Int32

Create a directory at path.

mknod(path : String, mode : Int32, rdev : UInt64) : Int32

Create a filesystem node (regular file, FIFO, socket, device, …) at path. rdev matters only for device nodes.

mount(args : Array(String)) : Int32

Mount this filesystem, handing args (argv-style) straight to libfuse. Don't override this.

open(path : String, fi : FileInfo) : Int32

Same as open but with the FileInfo (open flags + a settable file handle). Override this instead of open for handle/flag-aware behavior; by default it just delegates to the path-only form.

open(path : String) : Int32

Called when a file is opened. Return 0 for success.

opendir(path : String, fi : FileInfo) : Int32

Called when a directory is opened. Set fi.fh for a directory handle.

poll(path : String, fi : FileInfo, ph : Pointer(Void), reventsp : Pointer(UInt32)) : Int32

Poll for I/O readiness; set the ready events into reventsp. ph is an opaque poll handle for later notification.

read(path : String, size : Int32, offset : Int64, fi : FileInfo) : Bytes | Int32

Same as read but with the FileInfo (file handle set in open).

read(path : String, buffer : Bytes, offset : Int64, fi : FileInfo) : Int32

Buffer-filling escape hatch: write up to buffer.size bytes directly into buffer (the kernel's own read buffer) starting at offset, and return the number of bytes written, or a negative errno.

This avoids the allocate-and-copy of the Bytes-returning form, which is worth it for filesystems streaming large files. Override this or the Bytes form — by default this one calls the Bytes form and copies its result into buffer.

read(path : String, size : Int32, offset : Int64) : Bytes | Int32

Read up to size bytes from path starting at offset.

readdir(path : String, filler : DirFiller, fi : FileInfo) : Int32

Streaming escape hatch: push entries into filler (filler << name) as you discover them and return 0, or a negative errno. Avoids materializing the whole listing into an Array(String) — worth it for directories with very many entries. By default it calls the Array(String)-returning form and streams its result, so override one or the other.

readdir(path : String, fi : FileInfo) : Array(String) | Int32

Same as readdir but with the FileInfo (the handle set in opendir).

readdir(path : String) : Array(String) | Int32

Entries contained in the directory at path. Include "." and "..".

readlink(path : String) : String | Int32

Resolve the target of the symbolic link at path.

release(path : String, fi : FileInfo) : Int32

Called once when the last open reference to a file is released. Free any handle/state you allocated in open/create here.

releasedir(path : String, fi : FileInfo) : Int32

Called when a directory handle is released.

removexattr(path : String, name : String) : Int32

Remove extended attribute name.

rename(path : String, new_path : String, flags : UInt32) : Int32

Rename/move path to new_path.

rmdir(path : String) : Int32

Remove the directory at path.

setxattr(path : String, name : String, value : Bytes, flags : Int32) : Int32

Set extended attribute name to value. flags may be XATTR_CREATE (1, fail if it exists) or XATTR_REPLACE (2, fail if it doesn't).

statfs(path : String) : StatVFS | Int32

Filesystem statistics for path. Return a StatVFS.

symlink(target : String, link_path : String) : Int32

Create a symbolic link at link_path pointing to target.

truncate(path : String, size : Int64) : Int32

Change the size of the file at path.

unlink(path : String) : Int32

Remove the file at path.

utimens(path : String, atime : Time | Nil, mtime : Time | Nil) : Int32

Set the access and/or modification times of path. Either may be nil, meaning "leave that timestamp unchanged" (FUSE's UTIME_OMIT).

write(path : String, data : Bytes, offset : Int64, fi : FileInfo) : Int32

Same as write but with the FileInfo (file handle set in open).

write(path : String, data : Bytes, offset : Int64) : Int32

Write data to path at offset. Return the number of bytes written.