libretro.drivers.vfs.default¶

Default FileSystemDriver implementation backed by os and io.

See also

FileSystemDriver: The protocol this driver implements.

Classes

`DefaultFileSystemDriver`	Default `FileSystemDriver` implementation backed by `os` and `io`.
`StandardDirectoryHandle`	Default `DirectoryHandle` implementation backed by `os.scandir()`.
`StandardFileHandle`	Default `FileHandle` implementation backed by `io.FileIO`.

class StandardFileHandle[source]¶

Bases: FileHandle

Default FileHandle implementation backed by io.FileIO.

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

Open the file at path using io.FileIO.

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:

ValueError – If path is empty.
OSError – If the file cannot be opened.

__del__()[source]¶: Close the underlying file when this handle is garbage-collected.

close()[source]¶

Close the underlying file and release any associated resources.

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

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.

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.

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.

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.

read(buffer)[source]¶

Read bytes from the file into buffer.

Parameters:: buffer (bytearray | memoryview) – 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.

write(buffer)[source]¶

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

Parameters:: buffer (bytes | bytearray | memoryview) – 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.

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.

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.

property fileno¶

Return the OS-level file descriptor backing this handle.

Returns:: The integer file descriptor of the underlying io.FileIO.
Raises:: IOError – If the file is closed.

property vfs_handle¶

Return the retro_vfs_file_handle that represents this file in the VFS.

Returns:: The opaque VFS handle associated with this file.

classmethod __new__(*args, **kwargs)¶

class StandardDirectoryHandle[source]¶

Bases: DirectoryHandle

Default DirectoryHandle implementation backed by os.scandir().

__init__(path, include_hidden)[source]¶

Open the directory at path for iteration via os.scandir().

Parameters:

path (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.

__del__()[source]¶: Close the underlying scan iterator when this handle is garbage-collected.

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.

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.

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.

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)¶

class DefaultFileSystemDriver[source]¶

Bases: FileSystemDriver

Default FileSystemDriver implementation backed by os and io.

Open files and directories are tracked internally by their VFS handle ID so that they can be looked up when cores invoke the corresponding VFS callbacks.

__init__(version=3)[source]¶

Initialize the driver and declare which VFS interface version it advertises.

Parameters:: version (1 | 2 | 3) – The VFS interface version to report via version; must be 1, 2, or 3. Defaults to 3.

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

classmethod __new__(*args, **kwargs)¶

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()

property version¶

Return the VFS interface version implemented by this driver.

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