libretro.drivers.vfs.driver¶

Protocol definition for the virtual filesystem interface.

See also

libretro.api.vfs: The matching ctypes types and callback definitions.

Classes

`DirectoryHandle`	Represents an open directory in the virtual file system.
`FileHandle`	Represents an open file in the virtual file system.
`FileSystemDriver`	Protocol for backends that implement the libretro virtual filesystem interface.

class FileSystemDriver[source]¶

Bases: Protocol

Protocol for backends that implement the libretro virtual filesystem interface.

Implementations expose file and directory operations to cores using the same semantics as the C retro_vfs_* callbacks.

See also

libretro.api.vfs: The matching ctypes types and callback definitions.

abstract property version¶

Return the VFS interface version implemented by this driver.

Returns:: The supported VFS interface version (1, 2, or 3).

abstractmethod get_path(stream)[source]¶

Return the path that was used to open stream.

Parameters:: stream (retro_vfs_file_handle) – An open file handle previously returned by open().
Return type:: bytes | None
Returns:: The original path as bytes, or None if stream is unknown.

See also

retro_vfs_get_path_t()

abstractmethod open(path, mode, hints)[source]¶

Open the file at path and return a handle to it.

Parameters:

path (bytes) – Path of the file to open, encoded as bytes.
mode (VfsFileAccess) – Access mode flags controlling read/write behavior.
hints (VfsFileAccessHint) – Hints describing the intended access pattern.

Return type:

retro_vfs_file_handle | None

Returns:

A new retro_vfs_file_handle, or None if the file could not be opened.

See also

retro_vfs_open_t()

abstractmethod close(stream)[source]¶

Close the file referenced by stream.

Parameters:: stream (retro_vfs_file_handle) – A file handle previously returned by open().
Return type:: bool
Returns:: True if the file was closed successfully, False otherwise.

See also

retro_vfs_close_t()

abstractmethod size(stream)[source]¶

Return the size of the file referenced by stream.

Parameters:: stream (retro_vfs_file_handle) – An open file handle previously returned by open().
Return type:: int
Returns:: The size of the file in bytes, or a negative value on failure.

See also

retro_vfs_size_t()

abstractmethod truncate(stream, length)[source]¶

Truncate (or extend) the file referenced by stream to length bytes.

Parameters:

stream (retro_vfs_file_handle) – An open file handle previously returned by open().
length (int) – The new size of the file, in bytes.

Return type:

bool

Returns:

True if the operation succeeded, False otherwise.

See also

retro_vfs_truncate_t()

abstractmethod tell(stream)[source]¶

Return the current read/write offset within stream.

Parameters:: stream (retro_vfs_file_handle) – An open file handle previously returned by open().
Return type:: int
Returns:: The current byte offset from the start of the file, or a negative value on failure.

See also

retro_vfs_tell_t()

abstractmethod seek(stream, offset, whence)[source]¶

Move stream’s read/write offset to offset relative to whence.

Parameters:

stream (retro_vfs_file_handle) – An open file handle previously returned by open().
offset (int) – The new offset, in bytes, relative to whence.
whence (VfsSeekPosition) – The reference position used to interpret offset.

Return type:

int

Returns:

The resulting absolute offset, or a negative value on failure.

See also

retro_vfs_seek_t()

abstractmethod read(stream, buffer)[source]¶

Read bytes from stream into buffer.

Parameters:

stream (retro_vfs_file_handle) – An open file handle previously returned by open().
buffer (memoryview[int]) – A writable buffer to receive the bytes that were read.

Return type:

int

Returns:

The number of bytes actually read, or a negative value on failure.

See also

retro_vfs_read_t()

abstractmethod write(stream, buffer)[source]¶

Write the contents of buffer to stream at its current offset.

Parameters:

stream (retro_vfs_file_handle) – An open file handle previously returned by open().
buffer (memoryview[int]) – A readable buffer holding the bytes to write.

Return type:

int

Returns:

The number of bytes actually written, or a negative value on failure.

See also

retro_vfs_write_t()

abstractmethod flush(stream)[source]¶

Flush any buffered data for stream to the underlying storage.

Parameters:: stream (retro_vfs_file_handle) – An open file handle previously returned by open().
Return type:: bool
Returns:: True if the flush succeeded, False otherwise.

See also

retro_vfs_flush_t()

abstractmethod remove(path)[source]¶

Delete the file at path.

Parameters:: path (bytes) – Path of the file to remove, encoded as bytes.
Return type:: bool
Returns:: True if the file was removed successfully, False otherwise.

See also

retro_vfs_remove_t()

abstractmethod rename(old_path, new_path)[source]¶

Rename or move the file at old_path to new_path.

Parameters:

old_path (bytes) – Existing path of the file, encoded as bytes.
new_path (bytes) – New path for the file, encoded as bytes.

Return type:

bool

Returns:

True if the rename succeeded, False otherwise.

See also

retro_vfs_rename_t()

abstractmethod stat(path)[source]¶

Return file metadata for path.

Parameters:: path (bytes) – Path of the entry to inspect, encoded as bytes.
Return type:: tuple[VfsStat, int] | None
Returns:: A pair of VfsStat flags and the entry size in bytes, or None if path does not exist.

See also

retro_vfs_stat_t()

abstractmethod mkdir(path)[source]¶

Create a directory at path.

Parameters:: path (bytes) – Path of the directory to create, encoded as bytes.
Return type:: VfsMkdirResult
Returns:: A VfsMkdirResult describing the outcome of the operation.

See also

retro_vfs_mkdir_t()

abstractmethod opendir(path, include_hidden)[source]¶

Open the directory at path for iteration.

Parameters:

path (bytes) – Path of the directory to open, encoded as bytes.
include_hidden (bool) – Whether hidden entries should be returned during iteration.

Return type:

retro_vfs_dir_handle | None

Returns:

A new retro_vfs_dir_handle, or None if the directory could not be opened.

See also

retro_vfs_opendir_t()

abstractmethod readdir(dir)[source]¶

Advance dir to its next entry.

Parameters:: dir (retro_vfs_dir_handle) – An open directory handle previously returned by opendir().
Return type:: bool
Returns:: True if a new entry is now available, False if the end was reached.

See also

retro_vfs_readdir_t()

abstractmethod dirent_get_name(dir)[source]¶

Return the name of the current entry in dir.

Parameters:: dir (retro_vfs_dir_handle) – An open directory handle previously returned by opendir().
Return type:: bytes | None
Returns:: The entry name as bytes, or None if no entry is available.

See also

retro_vfs_dirent_get_name_t()

abstractmethod dirent_is_dir(dir)[source]¶

Return whether the current entry in dir refers to a subdirectory.

Parameters:: dir (retro_vfs_dir_handle) – An open directory handle previously returned by opendir().
Return type:: bool
Returns:: True if the current entry is a directory, False otherwise.

See also

retro_vfs_dirent_is_dir_t()

abstractmethod closedir(dir)[source]¶

Close dir and release any associated resources.

Parameters:: dir (retro_vfs_dir_handle) – A directory handle previously returned by opendir().
Return type:: bool
Returns:: True if the directory was closed successfully, False otherwise.

See also

retro_vfs_closedir_t()

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class FileHandle[source]¶

Bases: Protocol

Represents an open file in the virtual file system.

This is a higher-level abstraction than the raw file handle provided by the VFS interface. Optional.

abstractmethod __init__(path, mode, hints)[source]¶

Open the file at path with the given access mode and hints.

Parameters:

path (bytes) – Path of the file to open, encoded as bytes.
mode (VfsFileAccess) – Access mode flags controlling read/write behavior.
hints (VfsFileAccessHint) – Hints describing the intended access pattern.

Raises:

OSError – If the file cannot be opened.

abstractmethod close()[source]¶

Close the underlying file and release any associated resources.

Return type:: bool
Returns:: True if the file was closed successfully, False otherwise.

abstract property path¶

Return the path that was used to open this file.

Returns:: The original path as bytes.
Raises:: IOError – If the file is closed.

abstract property size¶

Return the size of the open file in bytes.

Returns:: The current file size in bytes.
Raises:: IOError – If the file is closed.

abstractmethod tell()[source]¶

Return the current read/write offset within the file.

Return type:: int
Returns:: The current byte offset from the start of the file.
Raises:: IOError – If the file is closed.

abstractmethod seek(offset, whence)[source]¶

Move the file’s read/write offset to offset relative to whence.

Parameters:

offset (int) – The new offset, in bytes, relative to whence.
whence (VfsSeekPosition) – The reference position used to interpret offset.

Return type:

int

Returns:

The resulting absolute offset from the start of the file.

Raises:

IOError – If the file is closed.

abstractmethod read(buffer)[source]¶

Read bytes from the file into buffer.

Parameters:: buffer (memoryview[int]) – A writable buffer to receive the bytes that were read.
Return type:: int
Returns:: The number of bytes that were actually read.
Raises:: IOError – If the file is closed.

abstractmethod write(buffer)[source]¶

Write the contents of buffer to the file at the current offset.

Parameters:: buffer (memoryview[int]) – A readable buffer holding the bytes to write.
Return type:: int
Returns:: The number of bytes that were actually written.
Raises:: IOError – If the file is closed.

abstractmethod flush()[source]¶

Flush any buffered data to the underlying storage.

Return type:: bool
Returns:: True if the flush succeeded, False otherwise.
Raises:: IOError – If the file is closed.

abstractmethod truncate(length)[source]¶

Truncate (or extend) the file to length bytes.

Parameters:: length (int) – The new size of the file, in bytes.
Return type:: bool
Returns:: True if the operation succeeded, False otherwise.
Raises:: IOError – If the file is closed.

classmethod __new__(*args, **kwargs)¶

class DirectoryHandle[source]¶

Bases: Protocol

Represents an open directory in the virtual file system.

This is a higher-level abstraction than the raw directory handle provided by the VFS interface. Optional.

abstractmethod __init__(dir, include_hidden)[source]¶

Open the directory at dir for iteration.

Parameters:

dir (bytes) – Path of the directory to open, encoded as bytes.
include_hidden (bool) – Whether hidden entries should be returned during iteration.

Raises:

OSError – If the directory cannot be opened.

abstractmethod readdir()[source]¶

Advance to the next entry in the directory.

Return type:: bool
Returns:: True if a new entry is now available, False if the end was reached.
Raises:: IOError – If the directory is closed.

abstract property dirent_name¶

Return the name of the current directory entry, if any.

Returns:: The entry name as bytes, or None if no entry is available.
Raises:: IOError – If the directory is closed.

abstract property dirent_is_dir¶

Return whether the current directory entry refers to a subdirectory.

Returns:

True if the current entry is a directory, False otherwise.

Raises:

IOError – If the directory is closed.
ValueError – If no current entry is available.

abstractmethod closedir()[source]¶

Close the directory and release any associated resources.

Return type:: bool
Returns:: True if the directory was closed successfully, False otherwise.

classmethod __new__(*args, **kwargs)¶