FUSE API Functions

pyfuse3.init(ops, mountpoint, options=default_options)

Initialize and mount FUSE file system

ops has to be an instance of the Operations class (or another class defining the same methods).

args has to be a set of strings. default_options provides some reasonable defaults. It is recommended to use these options as a basis and add or remove options as necessary. For example:

my_opts = set(pyfuse3.default_options)
my_opts.add('allow_other')
my_opts.discard('default_permissions')
pyfuse3.init(ops, mountpoint, my_opts)

Valid options are listed under struct fuse_opt fuse_mount_opts[] (in mount.c) and struct fuse_opt fuse_ll_opts[] (in fuse_lowlevel_c).

coroutine pyfuse3.main(min_tasks=1, max_tasks=99)

Run FUSE main loop

pyfuse3.terminate()

Terminate FUSE main loop.

This function gracefully terminates the FUSE main loop (resulting in the call to main() to return).

When called by a thread different from the one that runs the main loop, the call must be wrapped with trio.from_thread.run_sync. The necessary trio_token argument can (for convience) be retrieved from the trio_token module attribute.

pyfuse3.close(unmount=True)

Clean up and ensure filesystem is unmounted

If unmount is False, only clean up operations are peformed, but the file system is not explicitly unmounted.

Normally, the filesystem is unmounted by the user calling umount(8) or fusermount(1), which then terminates the FUSE main loop. However, the loop may also terminate as a result of an exception or a signal. In this case the filesystem remains mounted, but any attempt to access it will block (while the filesystem process is still running) or (after the filesystem process has terminated) return an error. If unmount is True, this function will ensure that the filesystem is properly unmounted.

Note: if the connection to the kernel is terminated via the /sys/fs/fuse/connections/ interface, this function will not unmount the filesystem even if unmount is True.

pyfuse3.invalidate_inode(fuse_ino_t inode, attr_only=False)

Invalidate cache for inode

Instructs the FUSE kernel module to forgot cached attributes and data (unless attr_only is True) for inode.

This operation may block if writeback caching is active and there is dirty data for the inode that is to be invalidated. Unfortunately there is no way to return control to the event loop until writeback is complete (leading to a deadlock if the necessary write() requests cannot be processed by the filesystem). Unless writeback caching is disabled, this function should therefore be called from a separate thread.

If the operation is not supported by the kernel, raises OSError with errno ENOSYS.

pyfuse3.invalidate_entry(fuse_ino_t inode_p, name, fuse_ino_t deleted=0)

Invalidate directory entry

Instructs the FUSE kernel module to forget about the directory entry name in the directory with inode inode_p.

If the inode passed as deleted matches the inode that is currently associated with name by the kernel, any inotify watchers of this inode are informed that the entry has been deleted.

If there is a pending filesystem operation that is related to the parent directory or directory entry, this function will block until that operation has completed. Therefore, to avoid a deadlock this function must not be called while handling a related request, nor while holding a lock that could be needed for handling such a request.

As for kernel 4.18, a “related operation” is a lookup, symlink, mknod, mkdir, unlink, rename, link or create request for the parent, and a setattr, unlink, rmdir, rename, setxattr, removexattr or readdir request for the inode itself.

For technical reasons, this function can also not return control to the main event loop but will actually block. To return control to the event loop while this function is running, call it in a separate thread using trio.run_sync_in_worker_thread. A less complicated alternative is to use the invalidate_entry_async function instead.

pyfuse3.invalidate_entry_async(inode_p, name, deleted=0, ignore_enoent=False)

Asynchronously invalidate directory entry

This function performs the same operation as invalidate_entry, but does so asynchronously in a separate thread. This avoids the deadlocks that may occur when using invalidate_entry from within a request handler, but means that the function generally returns before the kernel has actually invalidated the entry, and that no errors can be reported (they will be logged though).

The directory entries that are to be invalidated are put in an unbounded queue which is processed by a single thread. This means that if the entry at the beginning of the queue cannot be invalidated yet because a related file system operation is still in progress, none of the other entries will be processed and repeated calls to this function will result in continued growth of the queue.

If there are errors, an exception is logged using the logging module.

If ignore_enoent is True, ignore ENOENT errors (which occur if the kernel doesn’t actually have knowledge of the entry that is to be removed).

pyfuse3.notify_store(inode, offset, data)

Store data in kernel page cache

Sends data for the kernel to store it in the page cache for inode at offset. If this provides data beyond the current file size, the file is automatically extended.

If this function raises an exception, the store may still have completed partially.

If the operation is not supported by the kernel, raises OSError with errno ENOSYS.

pyfuse3.readdir_reply(ReaddirToken token, name, EntryAttributes attr, off_t next_id)

Report a directory entry in response to a readdir request.

This function should be called by the readdir handler to provide the list of directory entries. The function should be called once for each directory entry, until it returns False.

token must be the token received by the readdir handler.

name and must be the name of the directory entry and attr an

EntryAttributes instance holding its attributes.

next_id must be a 64-bit integer value that uniquely identifies the current position in the list of directory entries. It may be passed back to a later readdir call to start another listing at the right position. This value should be robust in the presence of file removals and creations, i.e. if files are created or removed after a call to readdir and readdir is called again with start_id set to any previously supplied next_id values, under no circumstances must any file be reported twice or skipped over.

pyfuse3.trio_token

Set to the value returned by trio.lowlevel.current_trio_token() while main() is running. Can be used by other threads to run code in the main loop through trio.from_thread.run.