libretro.api.vfs¶

Virtual filesystem (VFS) interface types and callbacks.

See also

FileSystemDriver: The Protocol that uses these types to implement VFS support in libretro.py.
libretro.drivers.vfs: libretro.py’s included FileSystemDriver implementations.

Module Attributes

`retro_vfs_get_path_t`	Return the path that was used to open a VFS file.
`retro_vfs_open_t`	Open a file for reading, writing, or both.
`retro_vfs_close_t`	Close an open VFS file and release its resources.
`retro_vfs_size_t`	Return the size of an open VFS file.
`retro_vfs_truncate_t`	Set the length of an open VFS file.
`retro_vfs_tell_t`	Return the current read/write position of an open VFS file.
`retro_vfs_seek_t`	Set the read/write position of an open VFS file.
`retro_vfs_read_t`	Read data from an open VFS file.
`retro_vfs_write_t`	Write data to an open VFS file.
`retro_vfs_flush_t`	Flush pending writes for an open VFS file.
`retro_vfs_remove_t`	Delete the file at the given path.
`retro_vfs_rename_t`	Rename a file from one path to another.
`retro_vfs_stat_t`	Get information about a file at the given path.
`retro_vfs_mkdir_t`	Create a directory at the given path.
`retro_vfs_opendir_t`	Open a directory so its contents can be enumerated.
`retro_vfs_readdir_t`	Advance to the next directory entry.
`retro_vfs_dirent_get_name_t`	Return the filename of the current directory entry.
`retro_vfs_dirent_is_dir_t`	Return whether the current directory entry is itself a directory.
`retro_vfs_closedir_t`	Close an open VFS directory handle.

Classes

`VfsFileAccess`	File access mode flags for VFS operations.
`VfsFileAccessHint`	Hints for file access patterns.
`VfsMkdirResult`	Return codes for VFS mkdir operations.
`VfsSeekPosition`	Seek origin for VFS seek operations.
`VfsStat`	Flags returned by VFS stat operations.
`retro_vfs_dir_handle`	Opaque handle for an open VFS directory.
`retro_vfs_file_handle`	Opaque handle for an open VFS file.
`retro_vfs_interface`	Corresponds to `retro_vfs_interface` in `libretro.h`.
`retro_vfs_interface_info`	Corresponds to `retro_vfs_interface_info` in `libretro.h`.

class retro_vfs_file_handle[source]¶

Bases: Structure

Opaque handle for an open VFS file.

Corresponds to retro_vfs_file_handle in libretro.h.

Note

Unlike most other ctypes-wrapped structs in libretro.py, the fields in this class are not part of libretro.h. They are provided as a convenience for FileSystemDriver implementations.

Cores should treat instances of this class as opaque handles and _not_ access or modify its fields directly.

See also

FileSystemDriver.open(): The suggested method for creating instances of this class.

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

Initialize a new file handle with the given values.

..seealso::: retro_vfs_open_t

id¶: Opaque identifier for this file handle. The FileSystemDriver that creates this handle can assign any value, but it should be unique among opened files.

path¶: Path that was used to open this file.

mode¶

File access mode flags.

See also

VfsFileAccess: The flags that can be set in this field.

hints¶

File access hint flags.

See also

VfsFileAccessHint: The flags that can be set in this field.

classmethod __new__(*args, **kwargs)¶

class retro_vfs_dir_handle[source]¶

Bases: Structure

Opaque handle for an open VFS directory.

Corresponds to retro_vfs_dir_handle in libretro.h.

Note

Unlike most other ctypes-wrapped structs in libretro.py, the fields in this class are not part of libretro.h. They are provided as a convenience for FileSystemDriver implementations.

Cores should treat instances of this class as opaque handles and _not_ access or modify its fields directly.

See also

FileSystemDriver.opendir(): The method that creates instances of this class.

id¶: Opaque identifier for this directory handle. The FileSystemDriver that creates this handle can assign any value, but it should be unique among opened directories.

dir¶: Path to the open directory.

include_hidden¶: Whether hidden entries are included when enumerating the directory’s contents.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

class VfsFileAccess[source]¶

Bases: IntFlag

File access mode flags for VFS operations.

Corresponds to the RETRO_VFS_FILE_ACCESS_* constants in libretro.h.

>>> from libretro.api import VfsFileAccess
>>> VfsFileAccess.READ
<VfsFileAccess.READ: 1>

READ = 1¶

WRITE = 2¶

READ_WRITE = 3¶

UPDATE_EXISTING = 4¶

READ_WRITE_EXISTING = 7¶

property open_flag¶

Returns the Python open() mode string for this access mode.

>>> from libretro.api import VfsFileAccess
>>> VfsFileAccess.READ.open_flag
'rb'

__new__(value)¶

other in self¶: Returns True if self has at least the same flags set as other.

iter(self)¶: Returns flags in definition order.

len(self)¶: Return the number of members (no aliases)

classmethod self[name]¶: Return the member matching name.

__init__()¶

retro_vfs_get_path_t¶

Return the path that was used to open a VFS file.

Registered by the frontend and called by the core.

Parameters:: stream – Pointer to an open retro_vfs_file_handle.
Returns:: The path that was used to open stream, as a bytes string. The string is owned by the frontend and must not be modified.

Corresponds to retro_vfs_get_path_t in libretro.h.

retro_vfs_open_t¶

Open a file for reading, writing, or both.

Registered by the frontend and called by the core.

Parameters:

path – The path of the file to open.
mode – A bitmask of VfsFileAccess flags.
hints – A bitmask of VfsFileAccessHint flags.

Returns:

A c_void_ptr to a new retro_vfs_file_handle on success, or None on failure (including when path names a directory).

Corresponds to retro_vfs_open_t in libretro.h.

retro_vfs_close_t¶

Close an open VFS file and release its resources.

Registered by the frontend and called by the core. After this returns the handle is no longer valid.

Parameters:: stream – Pointer to the retro_vfs_file_handle to close.
Returns:: 0 on success, -1 on failure or if stream is None.

Corresponds to retro_vfs_close_t in libretro.h.

retro_vfs_size_t¶

Return the size of an open VFS file.

Registered by the frontend and called by the core.

Parameters:: stream – Pointer to the retro_vfs_file_handle to query.
Returns:: The size of the file in bytes, or -1 on error.

Corresponds to retro_vfs_size_t in libretro.h.

retro_vfs_truncate_t¶

Set the length of an open VFS file.

Registered by the frontend and called by the core. Shorter length values discard the trailing bytes; longer values pad with platform-defined contents.

Parameters:

stream – Pointer to the retro_vfs_file_handle to truncate.
length – New length of the file, in bytes.

Returns:

0 on success, -1 on failure.

Corresponds to retro_vfs_truncate_t in libretro.h.

retro_vfs_tell_t¶

Return the current read/write position of an open VFS file.

Registered by the frontend and called by the core.

Parameters:: stream – Pointer to the retro_vfs_file_handle to query.
Returns:: The current stream position in bytes, or -1 on error.

Corresponds to retro_vfs_tell_t in libretro.h.

retro_vfs_seek_t¶

Set the read/write position of an open VFS file.

Registered by the frontend and called by the core.

Parameters:

stream – Pointer to the retro_vfs_file_handle to seek.
offset – New offset in bytes, relative to seek_position.
seek_position – A VfsSeekPosition indicating the seek origin.

Returns:

The resulting stream position, or -1 on error.

Corresponds to retro_vfs_seek_t in libretro.h.

retro_vfs_read_t¶

Read data from an open VFS file.

Registered by the frontend and called by the core.

Parameters:

stream – Pointer to the retro_vfs_file_handle to read from.
s – A c_void_ptr to the buffer that will receive the data.
len – Maximum number of bytes to read.

Returns:

The number of bytes actually read, or -1 on error.

Corresponds to retro_vfs_read_t in libretro.h.

retro_vfs_write_t¶

Write data to an open VFS file.

Registered by the frontend and called by the core.

Parameters:

stream – Pointer to the retro_vfs_file_handle to write to.
s – A c_void_ptr to the buffer of bytes to write.
len – Number of bytes to write from s.

Returns:

The number of bytes actually written, or -1 on error.

Corresponds to retro_vfs_write_t in libretro.h.

retro_vfs_flush_t¶

Flush pending writes for an open VFS file.

Registered by the frontend and called by the core.

Parameters:: stream – Pointer to the retro_vfs_file_handle to flush.
Returns:: 0 on success, -1 on failure.

Corresponds to retro_vfs_flush_t in libretro.h.

retro_vfs_remove_t¶

Delete the file at the given path.

Registered by the frontend and called by the core.

Parameters:: path – Path of the file to delete.
Returns:: 0 on success, -1 on failure.

Corresponds to retro_vfs_remove_t in libretro.h.

retro_vfs_rename_t¶

Rename a file from one path to another.

Registered by the frontend and called by the core.

Parameters:

old_path – Path to an existing file.
new_path – Destination path; must not refer to an existing file.

Returns:

0 on success, -1 on failure.

Corresponds to retro_vfs_rename_t in libretro.h.

retro_vfs_stat_t¶

Get information about a file at the given path.

Registered by the frontend and called by the core.

Parameters:

path – Path of the file to query.
size – Pointer to an c_int32 that receives the file’s size in bytes, or None to ignore the size.

Returns:

A bitmask of VfsStat flags, or 0 if path does not refer to a valid file.

Corresponds to retro_vfs_stat_t in libretro.h.

retro_vfs_mkdir_t¶

Create a directory at the given path.

Registered by the frontend and called by the core.

Parameters:: dir – Path of the directory to create.
Returns:: A VfsMkdirResult value; 0 if the directory was created, -2 if it already exists, or -1 for any other error.

Corresponds to retro_vfs_mkdir_t in libretro.h.

retro_vfs_opendir_t¶

Open a directory so its contents can be enumerated.

Registered by the frontend and called by the core.

Parameters:

dir – Path to an existing directory.
include_hidden – True to include hidden files in the listing. The exact semantics depend on the platform.

Returns:

A c_void_ptr to a new retro_vfs_dir_handle on success, or None on failure.

Corresponds to retro_vfs_opendir_t in libretro.h.

retro_vfs_readdir_t¶

Advance to the next directory entry.

Registered by the frontend and called by the core.

Parameters:: dirstream – Pointer to the retro_vfs_dir_handle to advance.
Returns:: True if a new entry is available, False if no more entries remain.

Corresponds to retro_vfs_readdir_t in libretro.h.

retro_vfs_dirent_get_name_t¶

Return the filename of the current directory entry.

Registered by the frontend and called by the core. The returned pointer is valid until the next call to retro_vfs_readdir_t or retro_vfs_closedir_t on this handle.

Parameters:: dirstream – Pointer to the retro_vfs_dir_handle to query.
Returns:: The current entry’s filename as a bytes string, or None on error.

Corresponds to retro_vfs_dirent_get_name_t in libretro.h.

retro_vfs_dirent_is_dir_t¶

Return whether the current directory entry is itself a directory.

Registered by the frontend and called by the core.

Parameters:: dirstream – Pointer to the retro_vfs_dir_handle to query.
Returns:: True if the current entry names a subdirectory, False otherwise or on error.

Corresponds to retro_vfs_dirent_is_dir_t in libretro.h.

retro_vfs_closedir_t¶

Close an open VFS directory handle.

Registered by the frontend and called by the core. After this returns the handle is no longer valid.

Parameters:: dirstream – Pointer to the retro_vfs_dir_handle to close.
Returns:: 0 on success, -1 on failure.

Corresponds to retro_vfs_closedir_t in libretro.h.

class retro_vfs_interface[source]¶

Bases: Structure

Corresponds to retro_vfs_interface in libretro.h.

A complete set of callbacks for virtual filesystem operations.

>>> from libretro.api import retro_vfs_interface
>>> vfs = retro_vfs_interface()
>>> vfs.open is None
True

get_path¶: Returns the path of an open file handle.

open¶: Opens a file with the given path, mode, and hints.

close¶: Closes an open file handle.

size¶: Returns the size of an open file in bytes.

tell¶: Returns the current read/write position.

seek¶: Sets the current read/write position.

read¶: Reads data from an open file.

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

write¶: Writes data to an open file.

flush¶: Flushes pending writes to an open file.

remove¶: Deletes a file at the given path.

rename¶: Renames a file from one path to another.

truncate¶: Sets an open file’s length.

stat¶: Gets status flags and size of a file.

mkdir¶: Creates a directory at the given path.

opendir¶: Opens a directory for iteration.

readdir¶: Advances to the next directory entry.

dirent_get_name¶: Returns the name of the current directory entry.

dirent_is_dir¶: Returns whether the current directory entry is a subdirectory.

closedir¶: Closes an open directory handle.

__deepcopy__(_)[source]¶: Return a shallow copy.

class retro_vfs_interface_info[source]¶

Bases: Structure

Corresponds to retro_vfs_interface_info in libretro.h.

Wraps a retro_vfs_interface pointer with a version number.

>>> from libretro.api import retro_vfs_interface_info
>>> info = retro_vfs_interface_info()
>>> info.required_interface_version
0

__init__(*args, **kwargs)¶

classmethod __new__(*args, **kwargs)¶

required_interface_version¶: Minimum VFS API version required by the core.

iface¶: VFS interface provided by the frontend.

__deepcopy__(memo=None)[source]¶: Return a deep copy of this object, including all subobjects. Intended for use with copy.deepcopy().

class VfsFileAccessHint[source]¶

Bases: IntFlag

Hints for file access patterns.

>>> from libretro.api import VfsFileAccessHint
>>> VfsFileAccessHint.FREQUENT_ACCESS
<VfsFileAccessHint.FREQUENT_ACCESS: 1>

__new__(value)¶

other in self¶: Returns True if self has at least the same flags set as other.

iter(self)¶: Returns flags in definition order.

len(self)¶: Return the number of members (no aliases)

classmethod self[name]¶: Return the member matching name.

__init__()¶

NONE = 0¶

FREQUENT_ACCESS = 1¶

class VfsSeekPosition[source]¶

Bases: IntEnum

Seek origin for VFS seek operations.

>>> from libretro.api import VfsSeekPosition
>>> VfsSeekPosition.START
<VfsSeekPosition.START: 0>

__new__(value)¶

classmethod value in self¶

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members. 3) value is a pseudo-member (flags)

classmethod self[name]¶: Return the member matching name.

__init__()¶

classmethod iter(self)¶: Return members in definition order.

classmethod len(self)¶: Return the number of members (no aliases)

START = 0¶

CURRENT = 1¶

END = 2¶

class VfsStat[source]¶

Bases: IntFlag

Flags returned by VFS stat operations.

>>> from libretro.api import VfsStat
>>> VfsStat.IS_DIRECTORY
<VfsStat.IS_DIRECTORY: 2>

__new__(value)¶

other in self¶: Returns True if self has at least the same flags set as other.

iter(self)¶: Returns flags in definition order.

len(self)¶: Return the number of members (no aliases)

classmethod self[name]¶: Return the member matching name.

__init__()¶

IS_VALID = 1¶

IS_DIRECTORY = 2¶

IS_CHARACTER_SPECIAL = 4¶

class VfsMkdirResult[source]¶

Bases: IntEnum

Return codes for VFS mkdir operations.

>>> from libretro.api import VfsMkdirResult
>>> VfsMkdirResult.SUCCESS
<VfsMkdirResult.SUCCESS: 0>

__new__(value)¶

classmethod value in self¶

Return True if value is in cls.

value is in cls if: 1) value is a member of cls, or 2) value is the value of one of the cls’s members. 3) value is a pseudo-member (flags)

classmethod self[name]¶: Return the member matching name.

__init__()¶

classmethod iter(self)¶: Return members in definition order.

classmethod len(self)¶: Return the number of members (no aliases)

SUCCESS = 0¶

ERROR = -1¶

ALREADY_EXISTS = -2¶