Documentation

Opens up a read-only container for the application's filesystem.

By default, SDL_OpenTitleStorage uses the generic storage implementation. When the path override is not provided, the generic implementation will use the output of SDL_GetBasePath as the base path.

override

a path to override the backend's default title root.

props

a property list that may contain backend-specific information.

Returns

a title storage container on success or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CloseStorage, sDL_GetStorageFileSize, sDL_OpenUserStorage, sDL_ReadStorageFile

C declaration

SDL_OpenTitleStorage, defined at SDL3/SDL_storage.h 353:43

Since: 3.2.0

Opens up a container for a user's unique read/write filesystem.

While title storage can generally be kept open throughout runtime, user storage should only be opened when the client is ready to read/write files. This allows the backend to properly batch file operations and flush them when the container has been closed; ensuring safe and optimal save I/O.

org

the name of your organization.

app

the name of your application.

props

a property list that may contain backend-specific information.

Returns

a user storage container on success or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CloseStorage, sDL_GetStorageFileSize, sDL_GetStorageSpaceRemaining, sDL_OpenTitleStorage, sDL_ReadStorageFile, sDL_StorageReady, sDL_WriteStorageFile

C declaration

SDL_OpenUserStorage, defined at SDL3/SDL_storage.h 379:43

Since: 3.2.0

Opens up a container for local filesystem storage.

This is provided for development and tools. Portable applications should use SDL_OpenTitleStorage() for access to game data and SDL_OpenUserStorage() for access to user data.

path

the base path prepended to all storage paths, or NULL for no base path.

Returns

a filesystem storage container on success or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CloseStorage, sDL_GetStorageFileSize, sDL_GetStorageSpaceRemaining, sDL_OpenTitleStorage, sDL_OpenUserStorage, sDL_ReadStorageFile, sDL_WriteStorageFile

C declaration

SDL_OpenFileStorage, defined at SDL3/SDL_storage.h 403:43

Since: 3.2.0

Opens up a container using a client-provided storage interface.

Applications do not need to use this function unless they are providing their own SDL_Storage implementation. If you just need an SDL_Storage, you should use the built-in implementations in SDL, like SDL_OpenTitleStorage() or SDL_OpenUserStorage().

This function makes a copy of iface and the caller does not need to keep it around after this call.

iface

the interface that implements this storage, initialized using SDL_INIT_INTERFACE().

userdata

the pointer that will be passed to the interface functions.

Returns

a storage container on success or NULL on failure; call SDL_GetError() for more information.

See also

sDL_CloseStorage, sDL_GetStorageFileSize, sDL_GetStorageSpaceRemaining, SDL_INIT_INTERFACE, sDL_ReadStorageFile, sDL_StorageReady, sDL_WriteStorageFile

C declaration

SDL_OpenStorage, defined at SDL3/SDL_storage.h 432:43

Since: 3.2.0

Closes and frees a storage container.

storage

a storage container to close.

Returns

true if the container was freed with no errors, false otherwise; call SDL_GetError() for more information. Even if the function returns an error, the container data will be freed; the error is only for informational purposes.

See also

sDL_OpenFileStorage, sDL_OpenStorage, sDL_OpenTitleStorage, sDL_OpenUserStorage

C declaration

SDL_CloseStorage, defined at SDL3/SDL_storage.h 450:34

Since: 3.2.0

Checks if the storage container is ready to use.

This function should be called in regular intervals until it returns true - however, it is not recommended to spinwait on this call, as the backend may depend on a synchronous message loop. You might instead poll this in your game's main loop while processing events and drawing a loading screen.

storage

a storage container to query.

Returns

true if the container is ready, false otherwise.

C declaration

SDL_StorageReady, defined at SDL3/SDL_storage.h 465:34

Since: 3.2.0

Query the size of a file within a storage container.

storage

a storage container to query.

path

the relative path of the file to query.

length

a pointer to be filled with the file's length.

Returns

true if the file could be queried or false on failure; call SDL_GetError() for more information.

See also

sDL_ReadStorageFile, sDL_StorageReady

C declaration

SDL_GetStorageFileSize, defined at SDL3/SDL_storage.h 481:34

Since: 3.2.0

Synchronously read a file from a storage container into a client-provided buffer.

The value of length must match the length of the file exactly; call SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in a future release.

storage

a storage container to read from.

path

the relative path of the file to read.

destination

a client-provided buffer to read the file into.

length

the length of the destination buffer.

Returns

true if the file was read or false on failure; call SDL_GetError() for more information.

See also

sDL_GetStorageFileSize, sDL_StorageReady, sDL_WriteStorageFile

C declaration

SDL_ReadStorageFile, defined at SDL3/SDL_storage.h 504:34

Since: 3.2.0

Synchronously write a file from client memory into a storage container.

storage

a storage container to write to.

path

the relative path of the file to write.

source

a client-provided buffer to write from.

length

the length of the source buffer.

Returns

true if the file was written or false on failure; call SDL_GetError() for more information.

See also

sDL_GetStorageSpaceRemaining, sDL_ReadStorageFile, sDL_StorageReady

C declaration

SDL_WriteStorageFile, defined at SDL3/SDL_storage.h 522:34

Since: 3.2.0

Create a directory in a writable storage container.

storage

a storage container.

path

the path of the directory to create.

Returns

true on success or false on failure; call SDL_GetError() for more information.

See also

sDL_StorageReady

C declaration

SDL_CreateStorageDirectory, defined at SDL3/SDL_storage.h 536:34

Since: 3.2.0

Enumerate a directory in a storage container through a callback function.

This function provides every directory entry through an app-provided callback, called once for each directory entry, until all results have been provided or the callback returns either SDL_ENUM_SUCCESS or SDL_ENUM_FAILURE.

This will return false if there was a system problem in general, or if a callback returns SDL_ENUM_FAILURE. A successful return means a callback returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries were enumerated.

If path is NULL, this is treated as a request to enumerate the root of the storage container's tree. An empty string also works for this.

storage

a storage container.

path

the path of the directory to enumerate, or NULL for the root.

callback

a function that is called for each entry in the directory.

userdata

a pointer that is passed to callback.

Returns

true on success or false on failure; call SDL_GetError() for more information.

See also

sDL_StorageReady

C declaration

SDL_EnumerateStorageDirectory, defined at SDL3/SDL_storage.h 565:34

Since: 3.2.0

Remove a file or an empty directory in a writable storage container.

storage

a storage container.

path

the path to remove from the filesystem.

Returns

true on success or false on failure; call SDL_GetError() for more information.

See also

sDL_StorageReady

C declaration

SDL_RemoveStoragePath, defined at SDL3/SDL_storage.h 579:34

Since: 3.2.0

Rename a file or directory in a writable storage container.

storage

a storage container.

oldpath

the old path.

newpath

the new path.

Returns

true on success or false on failure; call SDL_GetError() for more information.

See also

sDL_StorageReady

C declaration

SDL_RenameStoragePath, defined at SDL3/SDL_storage.h 594:34

Since: 3.2.0

Copy a file in a writable storage container.

storage

a storage container.

oldpath

the old path.

newpath

the new path.

Returns

true on success or false on failure; call SDL_GetError() for more information.

See also

sDL_StorageReady

C declaration

SDL_CopyStorageFile, defined at SDL3/SDL_storage.h 609:34

Since: 3.2.0

Get information about a filesystem path in a storage container.

storage

a storage container.

path

the path to query.

info

a pointer filled in with information about the path, or NULL to check for the existence of a file.

Returns

true on success or false if the file doesn't exist, or another failure; call SDL_GetError() for more information.

See also

sDL_StorageReady

C declaration

SDL_GetStoragePathInfo, defined at SDL3/SDL_storage.h 625:34

Since: 3.2.0

Queries the remaining space in a storage container.

storage

a storage container to query.

Returns

the amount of remaining space, in bytes.

See also

sDL_StorageReady, sDL_WriteStorageFile

C declaration

SDL_GetStorageSpaceRemaining, defined at SDL3/SDL_storage.h 638:36

Since: 3.2.0

Enumerate a directory tree, filtered by pattern, and return a list.

Files are filtered out if they don't match the string in pattern, which may contain wildcard characters * (match everything) and ? (match one character). If pattern is NULL, no filtering is done and all results are returned. Subdirectories are permitted, and are specified with a path separator of '/'. Wildcard characters * and ? never match a path separator.

flags may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching case-insensitive.

The returned array is always NULL-terminated, for your iterating convenience, but if count is non-NULL, on return it will contain the number of items in the array, not counting the NULL terminator.

If path is NULL, this is treated as a request to enumerate the root of the storage container's tree. An empty string also works for this.

storage

a storage container.

path

the path of the directory to enumerate, or NULL for the root.

pattern

the pattern that files in the directory must match. Can be NULL.

flags

SDL_GLOB_* bitflags that affect this search.

count

on return, will be set to the number of items in the returned array. Can be NULL.

Returns

an array of strings on success or NULL on failure; call SDL_GetError() for more information. The caller should pass the returned pointer to SDL_free when done with it. This is a single allocation that should be freed with SDL_free() when it is no longer needed.

Thread safety

It is safe to call this function from any thread, assuming the storage object is thread-safe.

C declaration

SDL_GlobStorageDirectory, defined at SDL3/SDL_storage.h 678:37

Since: 3.2.0