SDL_IOFromFile - Man Page

SDL_IOFromFile — 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

#include "SDL3/SDL.h"

SDL_IOStream * SDL_IOFromFile(const char *file, const char *mode);

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:

· "r": Open a file for reading. The file must exist.

· "w": Create an empty file for writing. If a file with the same name
 already exists its content is erased and the file is treated as a new
 empty file.

· "a": Append to a file. Writing operations append data at the end of the
 file. The file is created if it does not exist.

· "r+": Open a file for update both reading and writing. The file must
 exist.

· "w+": Create an empty file for both reading and writing. If a file with
 the same name already exists its content is erased and the file is
 treated as a new empty file.

· "a+": Open a file for reading and appending. All writing operations are
 performed at the end of the file, protecting the previous content to be
 overwritten. You can reposition (fseek, rewind) the internal pointer to
 anywhere in the file for reading, but writing operations will move it
 back to the end of file. The file is created if it does not exist. 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.

file

a UTF-8 string representing the filename to open.

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.

This function is not thread safe.

This function is available since SDL 3.2.0.

·(3), SDL_CloseIO(3), ·(3), SDL_FlushIO(3), ·(3), SDL_ReadIO(3), ·(3), SDL_SeekIO(3), ·(3), SDL_TellIO(3), ·(3), SDL_WriteIO(3)

SDL_OpenIO(3).