Use this function to create a new SDL_IOStream structure for reading from and/or writing to a named file.
Defined in <SDL3/SDL_iostream.h>
const char *file, const char *mode); SDL_IOStream * SDL_IOFromFile(
const char * | file | a UTF-8 string representing the filename to open. |
const char * | mode | an ASCII string representing the mode to be used for opening the file. |
(SDL_IOStream *) Returns a pointer to the SDL_IOStream structure that is created or NULL on failure; call SDL_GetError() for more information.
The mode
string is treated roughly the same as in a call to the C library's fopen(), even if SDL doesn't happen to use fopen() behind the scenes.
Available mode
strings:
NOTE: In order to open a file as a binary file, a "b" character has to be included in the mode
string. This additional "b" character can either be appended at the end of the string (thus making the following compound modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). Additional characters may follow the sequence, although they should have no effect. For example, "t" is sometimes appended to make explicit the file is a text file.
This function supports Unicode filenames, but they must be encoded in UTF-8 format, regardless of the underlying operating system.
In Android, SDL_IOFromFile() can be used to open content:// URIs. As a fallback, SDL_IOFromFile() will transparently open a matching filename in the app's assets
.
Closing the SDL_IOStream will close SDL's internal file handle.
The following properties may be set at creation time by SDL:
SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER
: a pointer, that can be cast to a win32 HANDLE
, that this SDL_IOStream is using to access the filesystem. If the program isn't running on Windows, or SDL used some other method to access the filesystem, this property will not be set.SDL_PROP_IOSTREAM_STDIO_FILE_POINTER
: a pointer, that can be cast to a stdio FILE *
, that this SDL_IOStream is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set. PLEASE NOTE that if SDL is using a different C runtime than your app, trying to use this pointer will almost certainly result in a crash! This is mostly a problem on Windows; make sure you build SDL and your app with the same compiler and settings to avoid it.SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER
: a file descriptor that this SDL_IOStream is using to access the filesystem.SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER
: a pointer, that can be cast to an Android NDK AAsset *
, that this SDL_IOStream is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set.This function is available since SDL 3.0.0.