SDL_storage.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_error.h>`
`#include <SDL3/SDL_filesystem.h>`
`#include <SDL3/SDL_properties.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
Include dependency graph for SDL_storage.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | SDL_StorageInterface

## Typedefs

typedef struct SDL_Storage | SDL_Storage

## Functions

| SDL_COMPILE_TIME_ASSERT (SDL_StorageInterface_SIZE,(sizeof(void *)==4 &&sizeof(SDL_StorageInterface)==48)||(sizeof(void *)==8 &&sizeof(SDL_StorageInterface)==96))
SDL_Storage * | SDL_OpenTitleStorage (const char *override, SDL_PropertiesID props)
SDL_Storage * | SDL_OpenUserStorage (const char *org, const char *app, SDL_PropertiesID props)
SDL_Storage * | SDL_OpenFileStorage (const char *path)
SDL_Storage * | SDL_OpenStorage (const SDL_StorageInterface *iface, void *userdata)
bool | SDL_CloseStorage (SDL_Storage *storage)
bool | SDL_StorageReady (SDL_Storage *storage)
bool | SDL_GetStorageFileSize (SDL_Storage *storage, const char *path, Uint64 *length)
bool | SDL_ReadStorageFile (SDL_Storage *storage, const char *path, void *destination, Uint64 length)
bool | SDL_WriteStorageFile (SDL_Storage *storage, const char *path, const void *source, Uint64 length)
bool | SDL_CreateStorageDirectory (SDL_Storage *storage, const char *path)
bool | SDL_EnumerateStorageDirectory (SDL_Storage *storage, const char *path, SDL_EnumerateDirectoryCallback callback, void *userdata)
bool | SDL_RemoveStoragePath (SDL_Storage *storage, const char *path)
bool | SDL_RenameStoragePath (SDL_Storage *storage, const char *oldpath, const char *newpath)
bool | SDL_CopyStorageFile (SDL_Storage *storage, const char *oldpath, const char *newpath)
bool | SDL_GetStoragePathInfo (SDL_Storage *storage, const char *path, SDL_PathInfo *info)
Uint64 | SDL_GetStorageSpaceRemaining (SDL_Storage *storage)
char ** | SDL_GlobStorageDirectory (SDL_Storage *storage, const char *path, const char *pattern, SDL_GlobFlags flags, int *count)

## Typedef Documentation

## SDL_Storage

typedef struct SDL_Storage SDL_Storage

An abstract interface for filesystem access.

This is an opaque datatype. One can create this object using standard SDL functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create an object with a custom implementation using SDL_OpenStorage.

Since
  This struct is available since SDL 3.2.0.

Definition at line 332 of file SDL_storage.h.

## Function Documentation

## SDL_CloseStorage()

bool SDL_CloseStorage | ( | SDL_Storage * | storage | ) |

extern

Closes and frees a storage container.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_OpenFileStorage
  SDL_OpenStorage
  SDL_OpenTitleStorage
  SDL_OpenUserStorage

## SDL_COMPILE_TIME_ASSERT()

SDL_COMPILE_TIME_ASSERT | ( | SDL_StorageInterface_SIZE | ,
|  | (sizeof(void *)==4 &&sizeof(SDL_StorageInterface)==48)||(sizeof(void *)==8 &&sizeof(SDL_StorageInterface)==96) | )

## SDL_CopyStorageFile()

bool SDL_CopyStorageFile | ( | SDL_Storage * | storage,
|  | const char * | oldpath,
|  | const char * | newpath )

extern

Copy a file in a writable storage container.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady

## SDL_CreateStorageDirectory()

bool SDL_CreateStorageDirectory | ( | SDL_Storage * | storage,
|  | const char * | path )

extern

Create a directory in a writable storage container.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady

## SDL_EnumerateStorageDirectory()

bool SDL_EnumerateStorageDirectory | ( | SDL_Storage * | storage,
|  | const char * | path,
|  | SDL_EnumerateDirectoryCallback | callback,
|  | void * | userdata )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady

## SDL_GetStorageFileSize()

bool SDL_GetStorageFileSize | ( | SDL_Storage * | storage,
|  | const char * | path,
|  | Uint64 * | length )

extern

Query the size of a file within a storage container.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_ReadStorageFile
  SDL_StorageReady

## SDL_GetStoragePathInfo()

bool SDL_GetStoragePathInfo | ( | SDL_Storage * | storage,
|  | const char * | path,
|  | SDL_PathInfo * | info )

extern

Get information about a filesystem path in a storage container.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady

## SDL_GetStorageSpaceRemaining()

Uint64 SDL_GetStorageSpaceRemaining | ( | SDL_Storage * | storage | ) |

extern

Queries the remaining space in a storage container.

Parameters

  storage | a storage container to query.

Returns
  the amount of remaining space, in bytes.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady
  SDL_WriteStorageFile

## SDL_GlobStorageDirectory()

char ** SDL_GlobStorageDirectory | ( | SDL_Storage * | storage,
|  | const char * | path,
|  | const char * | pattern,
|  | SDL_GlobFlags | flags,
|  | int * | count )

extern

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.

Parameters

  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.

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

Since
  This function is available since SDL 3.2.0.

## SDL_OpenFileStorage()

SDL_Storage * SDL_OpenFileStorage | ( | const char * | path | ) |

extern

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.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CloseStorage
  SDL_GetStorageFileSize
  SDL_GetStorageSpaceRemaining
  SDL_OpenTitleStorage
  SDL_OpenUserStorage
  SDL_ReadStorageFile
  SDL_WriteStorageFile

## SDL_OpenStorage()

SDL_Storage * SDL_OpenStorage | ( | const SDL_StorageInterface * | iface,
|  | void * | userdata )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CloseStorage
  SDL_GetStorageFileSize
  SDL_GetStorageSpaceRemaining
  SDL_INIT_INTERFACE
  SDL_ReadStorageFile
  SDL_StorageReady
  SDL_WriteStorageFile

## SDL_OpenTitleStorage()

SDL_Storage * SDL_OpenTitleStorage | ( | const char * | override,
|  | SDL_PropertiesID | props )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CloseStorage
  SDL_GetStorageFileSize
  SDL_OpenUserStorage
  SDL_ReadStorageFile

## SDL_OpenUserStorage()

SDL_Storage * SDL_OpenUserStorage | ( | const char * | org,
|  | const char * | app,
|  | SDL_PropertiesID | props )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CloseStorage
  SDL_GetStorageFileSize
  SDL_GetStorageSpaceRemaining
  SDL_OpenTitleStorage
  SDL_ReadStorageFile
  SDL_StorageReady
  SDL_WriteStorageFile

## SDL_ReadStorageFile()

bool SDL_ReadStorageFile | ( | SDL_Storage * | storage,
|  | const char * | path,
|  | void * | destination,
|  | Uint64 | length )

extern

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.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetStorageFileSize
  SDL_StorageReady
  SDL_WriteStorageFile

## SDL_RemoveStoragePath()

bool SDL_RemoveStoragePath | ( | SDL_Storage * | storage,
|  | const char * | path )

extern

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

Parameters

  storage | a storage container.
  path | the path of the directory to enumerate.

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

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady

## SDL_RenameStoragePath()

bool SDL_RenameStoragePath | ( | SDL_Storage * | storage,
|  | const char * | oldpath,
|  | const char * | newpath )

extern

Rename a file or directory in a writable storage container.

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_StorageReady

## SDL_StorageReady()

bool SDL_StorageReady | ( | SDL_Storage * | storage | ) |

extern

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.

Parameters

  storage | a storage container to query.

Returns
  true if the container is ready, false otherwise.

Since
  This function is available since SDL 3.2.0.

## SDL_WriteStorageFile()

bool SDL_WriteStorageFile | ( | SDL_Storage * | storage,
|  | const char * | path,
|  | const void * | source,
|  | Uint64 | length )

extern

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

Parameters

  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.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetStorageSpaceRemaining
  SDL_ReadStorageFile
  SDL_StorageReady