SDL provides an abstract interface for reading and writing data streams. More...

Collaboration diagram for I/O Streams:

Classes
struct	SDL::IOStreamParam
	Safely wrap IOStream for non owning parameters. More...

class	SDL::IOStream
	The read/write operation structure. More...

struct	SDL::IOStreamRef
	Semi-safe reference for IOStream. More...

Typedefs
using	SDL::IOStreamRaw = SDL_IOStream *
	Alias to raw representation for IOStream.

using	SDL::IOStatus = SDL_IOStatus
	IOStream status, set by a read or write operation. More...

using	SDL::IOWhence = SDL_IOWhence
	Possible `whence` values for IOStream seeking. More...

using	SDL::IOStreamInterface = SDL_IOStreamInterface
	The function pointers that drive an IOStream. More...

Functions
IOStream	SDL::IOFromFile (StringParam file, StringParam mode)
	Use this function to create a new IOStream structure for reading from and/or writing to a named file. More...

IOStream	SDL::IOFromMem (TargetBytes mem)
	Use this function to prepare a read-write memory buffer for use with IOStream. More...

IOStream	SDL::IOFromConstMem (SourceBytes mem)
	Use this function to prepare a read-only memory buffer for use with IOStream. More...

IOStream	SDL::IOFromDynamicMem ()
	Use this function to create an IOStream that is backed by dynamically allocated memory. More...

IOStream	SDL::OpenIO (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStream. More...

void	SDL::CloseIO (IOStreamRaw context)
	Close and free an allocated IOStream structure. More...

PropertiesRef	SDL::GetIOProperties (IOStreamParam context)
	Get the properties associated with an IOStream. More...

IOStatus	SDL::GetIOStatus (IOStreamParam context)
	Query the stream status of an IOStream. More...

Sint64	SDL::GetIOSize (IOStreamParam context)
	Use this function to get the size of the data stream in an IOStream. More...

Sint64	SDL::SeekIO (IOStreamParam context, Sint64 offset, IOWhence whence)
	Seek within an IOStream data stream. More...

Sint64	SDL::TellIO (IOStreamParam context)
	Determine the current read/write offset in an IOStream data stream. More...

size_t	SDL::ReadIO (IOStreamParam context, TargetBytes buf)
	Read from a data source. More...

size_t	SDL::WriteIO (IOStreamParam context, SourceBytes buf)
	Write to an IOStream data stream. More...

size_t	SDL::IOprintf (IOStreamParam context, SDL_PRINTF_FORMAT_STRING const char *fmt,...)
	Print to an IOStream data stream. More...

size_t	SDL::IOvprintf (IOStreamParam context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap)
	Print to an IOStream data stream. More...

void	SDL::FlushIO (IOStreamParam context)
	Flush any buffered data in the stream. More...

StringResult	SDL::LoadFile (IOStreamParam src, bool closeio=true)
	Load all the data from an SDL data stream. More...

StringResult	SDL::LoadFile (StringParam file)
	Load all the data from a file path. More...

template<class T >
OwnArray< T >	SDL::LoadFileAs (StringParam file)
	Load all the data from a file path. More...

void	SDL::SaveFile (IOStreamParam src, SourceBytes data, bool closeio=false)
	Save all the data into an SDL data stream. More...

void	SDL::SaveFile (StringParam file, SourceBytes data)
	Save all the data into a file path. More...

Uint8	SDL::ReadU8 (IOStreamParam src)
	Use this function to read a byte from an IOStream. More...

Sint8	SDL::ReadS8 (IOStreamParam src)
	Use this function to read a signed byte from an IOStream. More...

Uint16	SDL::ReadU16LE (IOStreamParam src)
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format. More...

Sint16	SDL::ReadS16LE (IOStreamParam src)
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format. More...

Uint16	SDL::ReadU16BE (IOStreamParam src)
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format. More...

Sint16	SDL::ReadS16BE (IOStreamParam src)
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format. More...

Uint32	SDL::ReadU32LE (IOStreamParam src)
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format. More...

Sint32	SDL::ReadS32LE (IOStreamParam src)
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format. More...

Uint32	SDL::ReadU32BE (IOStreamParam src)
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format. More...

Sint32	SDL::ReadS32BE (IOStreamParam src)
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format. More...

Uint64	SDL::ReadU64LE (IOStreamParam src)
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format. More...

Sint64	SDL::ReadS64LE (IOStreamParam src)
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format. More...

Uint64	SDL::ReadU64BE (IOStreamParam src)
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format. More...

Sint64	SDL::ReadS64BE (IOStreamParam src)
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format. More...

void	SDL::WriteU8 (IOStreamParam dst, Uint8 value)
	Use this function to write a byte to an IOStream. More...

void	SDL::WriteS8 (IOStreamParam dst, Sint8 value)
	Use this function to write a signed byte to an IOStream. More...

void	SDL::WriteU16LE (IOStreamParam dst, Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data. More...

void	SDL::WriteS16LE (IOStreamParam dst, Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data. More...

void	SDL::WriteU16BE (IOStreamParam dst, Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data. More...

void	SDL::WriteS16BE (IOStreamParam dst, Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data. More...

void	SDL::WriteU32LE (IOStreamParam dst, Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data. More...

void	SDL::WriteS32LE (IOStreamParam dst, Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data. More...

void	SDL::WriteU32BE (IOStreamParam dst, Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data. More...

void	SDL::WriteS32BE (IOStreamParam dst, Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data. More...

void	SDL::WriteU64LE (IOStreamParam dst, Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data. More...

void	SDL::WriteS64LE (IOStreamParam dst, Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data. More...

void	SDL::WriteU64BE (IOStreamParam dst, Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data. More...

void	SDL::WriteS64BE (IOStreamParam dst, Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data. More...

static IOStream	SDL::IOStream::FromFile (StringParam file, StringParam mode)
	Use this function to create a new IOStream structure for reading from and/or writing to a named file. More...

static IOStream	SDL::IOStream::FromMem (TargetBytes mem)
	Use this function to prepare a read-write memory buffer for use with IOStream. More...

static IOStream	SDL::IOStream::FromConstMem (SourceBytes mem)
	Use this function to prepare a read-only memory buffer for use with IOStream. More...

static IOStream	SDL::IOStream::FromDynamicMem ()
	Use this function to create an IOStream that is backed by dynamically allocated memory. More...

static IOStream	SDL::IOStream::Open (const IOStreamInterface &iface, void *userdata)
	Create a custom IOStream. More...

void	SDL::IOStream::Close ()
	Close and free an allocated IOStream structure. More...

PropertiesRef	SDL::IOStream::GetProperties () const
	Get the properties associated with an IOStream. More...

IOStatus	SDL::IOStream::GetStatus () const
	Query the stream status of an IOStream. More...

Sint64	SDL::IOStream::GetSize () const
	Use this function to get the size of the data stream in an IOStream. More...

Sint64	SDL::IOStream::Seek (Sint64 offset, IOWhence whence)
	Seek within an IOStream data stream. More...

Sint64	SDL::IOStream::Tell () const
	Determine the current read/write offset in an IOStream data stream. More...

size_t	SDL::IOStream::Read (TargetBytes buf)
	Read from a data source. More...

size_t	SDL::IOStream::Write (SourceBytes buf)
	Write to an IOStream data stream. More...

size_t	SDL::IOStream::vprintf (SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap)
	Print to an IOStream data stream. More...

void	SDL::IOStream::Flush ()
	Flush any buffered data in the stream. More...

StringResult	SDL::IOStream::LoadFile ()
	Load all the data from an SDL data stream. More...

void	SDL::IOStream::SaveFile (SourceBytes data)
	Save all the data into an SDL data stream. More...

Uint16	SDL::IOStream::ReadU16LE ()
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format. More...

Sint16	SDL::IOStream::ReadS16LE ()
	Use this function to read 16 bits of little-endian data from an IOStream and return in native format. More...

Uint16	SDL::IOStream::ReadU16BE ()
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format. More...

Sint16	SDL::IOStream::ReadS16BE ()
	Use this function to read 16 bits of big-endian data from an IOStream and return in native format. More...

Uint32	SDL::IOStream::ReadU32LE ()
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format. More...

Sint32	SDL::IOStream::ReadS32LE ()
	Use this function to read 32 bits of little-endian data from an IOStream and return in native format. More...

Uint32	SDL::IOStream::ReadU32BE ()
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format. More...

Sint32	SDL::IOStream::ReadS32BE ()
	Use this function to read 32 bits of big-endian data from an IOStream and return in native format. More...

Uint64	SDL::IOStream::ReadU64LE ()
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format. More...

Sint64	SDL::IOStream::ReadS64LE ()
	Use this function to read 64 bits of little-endian data from an IOStream and return in native format. More...

Uint64	SDL::IOStream::ReadU64BE ()
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format. More...

Sint64	SDL::IOStream::ReadS64BE ()
	Use this function to read 64 bits of big-endian data from an IOStream and return in native format. More...

void	SDL::IOStream::WriteU8 (Uint8 value)
	Use this function to write a byte to an IOStream. More...

void	SDL::IOStream::WriteS8 (Sint8 value)
	Use this function to write a signed byte to an IOStream. More...

void	SDL::IOStream::WriteU16LE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data. More...

void	SDL::IOStream::WriteS16LE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as little-endian data. More...

void	SDL::IOStream::WriteU16BE (Uint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data. More...

void	SDL::IOStream::WriteS16BE (Sint16 value)
	Use this function to write 16 bits in native format to an IOStream as big-endian data. More...

void	SDL::IOStream::WriteU32LE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data. More...

void	SDL::IOStream::WriteS32LE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as little-endian data. More...

void	SDL::IOStream::WriteU32BE (Uint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data. More...

void	SDL::IOStream::WriteS32BE (Sint32 value)
	Use this function to write 32 bits in native format to an IOStream as big-endian data. More...

void	SDL::IOStream::WriteU64LE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data. More...

void	SDL::IOStream::WriteS64LE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as little-endian data. More...

void	SDL::IOStream::WriteU64BE (Uint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data. More...

void	SDL::IOStream::WriteS64BE (Sint64 value)
	Use this function to write 64 bits in native format to an IOStream as big-endian data. More...

Variables
constexpr IOStatus	SDL::IO_STATUS_READY
	Everything is ready (no errors and not EOF). More...

constexpr IOStatus	SDL::IO_STATUS_ERROR
	Read or write I/O error. More...

constexpr IOStatus	SDL::IO_STATUS_EOF = SDL_IO_STATUS_EOF
	End of file.

constexpr IOStatus	SDL::IO_STATUS_NOT_READY
	Non blocking I/O, not ready. More...

constexpr IOStatus	SDL::IO_STATUS_READONLY
	Tried to write a read-only buffer. More...

constexpr IOStatus	SDL::IO_STATUS_WRITEONLY
	Tried to read a write-only buffer. More...

constexpr IOWhence	SDL::IO_SEEK_SET
	Seek from the beginning of data. More...

constexpr IOWhence	SDL::IO_SEEK_CUR
	Seek relative to current read point. More...

constexpr IOWhence	SDL::IO_SEEK_END
	Seek relative to the end of data. More...

Detailed Description

It offers implementations for files, memory, etc, and the app can provide their own implementations, too.

IOStream is not related to the standard C++ iostream class, other than both are abstract interfaces to read/write data.

Typedef Documentation

◆ IOStatus

using SDL::IOStatus = typedef SDL_IOStatus

Since: This enum is available since SDL 3.2.0.

◆ IOStreamInterface

using SDL::IOStreamInterface = typedef SDL_IOStreamInterface

Applications can provide this struct to IOStream.Open() to create their own implementation of IOStream. This is not necessarily required, as SDL already offers several common types of I/O streams, via functions like IOStream.FromFile() and IOStream.FromMem().

This structure should be initialized using InitInterface()

Since: This struct is available since SDL 3.2.0.

See also: InitInterface

◆ IOWhence

using SDL::IOWhence = typedef SDL_IOWhence

These map to the same "whence" concept that fseek or lseek use in the standard C runtime.

Since: This enum is available since SDL 3.2.0.

Function Documentation

◆ Close()

void SDL::IOStream::Close ( )

inline

IOStream.Close() closes and cleans up the IOStream stream. It releases any resources used by the stream and frees the IOStream itself. This returns true on success, or false if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream for any reason, this function reports an error, but the IOStream is still invalid once this function returns.

This call flushes any buffered writes to the operating system, but there are no guarantees that those writes have gone to physical media; they might be in the OS's file cache, waiting to go to disk later. If it's absolutely crucial that writes go to disk immediately, so they are definitely stored even if the power fails before the file cache would have caught up, one should call IOStream.Flush() before closing. Note that flushing takes time and makes the system and your app operate less efficiently, so do so sparingly.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Open

◆ CloseIO()

void SDL::CloseIO ( IOStreamRaw context )

inline

IOStream.Close() closes and cleans up the IOStream stream. It releases any resources used by the stream and frees the IOStream itself. This returns true on success, or false if the stream failed to flush to its output (e.g. to disk).

Note that if this fails to flush the stream for any reason, this function reports an error, but the IOStream is still invalid once this function returns.

This call flushes any buffered writes to the operating system, but there are no guarantees that those writes have gone to physical media; they might be in the OS's file cache, waiting to go to disk later. If it's absolutely crucial that writes go to disk immediately, so they are definitely stored even if the power fails before the file cache would have caught up, one should call IOStream.Flush() before closing. Note that flushing takes time and makes the system and your app operate less efficiently, so do so sparingly.

Parameters

context IOStream structure to close.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Open

◆ Flush()

void SDL::IOStream::Flush ( )

inline

This function makes sure that any buffered data is written to the stream. Normally this isn't necessary but if the stream is a pipe or socket it guarantees that any pending data is sent.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Open; IOStream.Write

◆ FlushIO()

void SDL::FlushIO ( IOStreamParam context )

inline

This function makes sure that any buffered data is written to the stream. Normally this isn't necessary but if the stream is a pipe or socket it guarantees that any pending data is sent.

Parameters

context IOStream structure to flush.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Open; IOStream.Write

◆ FromConstMem()

IOStream SDL::IOStream::FromConstMem ( SourceBytes mem )

inlinestatic

This function sets up an IOStream struct based on a memory area of a certain size. It assumes the memory area is not writable.

Attempting to write to this IOStream stream will report an error without writing to the memory buffer.

This memory buffer is not copied by the IOStream; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to write to a memory buffer, you should use IOStream.FromMem() with a writable buffer of memory instead.

The following properties will be set at creation time by SDL:

prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a read-only buffer to feed an IOStreamRef stream.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromMem; IOStream.Close; IOStream.Read; IOStream.Seek; IOStream.Tell

◆ FromDynamicMem()

IOStream SDL::IOStream::FromDynamicMem ( )

inlinestatic

This supports the following properties to provide access to the memory and control over allocations:

prop::IOStream.DYNAMIC_MEMORY_POINTER: a pointer to the internal memory of the stream. This can be set to nullptr to transfer ownership of the memory to the application, which should free the memory with free(). If this is done, the next operation on the stream must be IOStream.Close().
prop::IOStream.DYNAMIC_CHUNKSIZE_NUMBER: memory will be allocated in multiples of this size, defaulting to 1024.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; IOStream.Read; IOStream.Seek; IOStream.Tell; IOStream.Write

◆ FromFile()

IOStream SDL::IOStream::FromFile	(	StringParam	file,
		StringParam	mode
	)

inlinestatic

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, IOStream.FromFile() can be used to open content:// URIs. As a fallback, IOStream.FromFile() will transparently open a matching filename in the app's assets.

Closing the IOStream will close SDL's internal file handle.

The following properties may be set at creation time by SDL:

prop::IOStream.WINDOWS_HANDLE_POINTER: a pointer, that can be cast to a win32 HANDLE, that this 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.
prop::IOStream.STDIO_FILE_POINTER: a pointer, that can be cast to a stdio FILE *, that this 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.
prop::IOStream.FILE_DESCRIPTOR_NUMBER: a file descriptor that this IOStream is using to access the filesystem.
prop::IOStream.ANDROID_AASSET_POINTER: a pointer, that can be cast to an Android NDK AAsset *, that this IOStream is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set.

Parameters

file	a UTF-8 string representing the filename to open.
mode	an ASCII string representing the mode to be used for opening the file.

Returns: a pointer to the IOStream structure that is created or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; IOStream.Flush; IOStream.Read; IOStream.Seek; IOStream.Tell; IOStream.Write

◆ FromMem()

IOStream SDL::IOStream::FromMem ( TargetBytes mem )

inlinestatic

This function sets up an IOStream struct based on a memory area of a certain size, for both read and write access.

This memory buffer is not copied by the IOStream; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to make sure the IOStream never writes to the memory buffer, you should use IOStream.FromConstMem() with a read-only buffer of memory instead.

The following properties will be set at creation time by SDL:

prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a buffer to feed an IOStream stream.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromConstMem; IOStream.Close; IOStream.Flush; IOStream.Read; IOStream.Seek; IOStream.Tell; IOStream.Write

◆ GetIOProperties()

PropertiesRef SDL::GetIOProperties ( IOStreamParam context )

inline

Parameters

context a pointer to an IOStream structure.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetIOSize()

Sint64 SDL::GetIOSize ( IOStreamParam context )

inline

Parameters

context the IOStream to get the size of the data stream from.

Returns: the size of the data stream in the IOStream on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetIOStatus()

IOStatus SDL::GetIOStatus ( IOStreamParam context )

inline

This information can be useful to decide if a short read or write was due to an error, an EOF, or a non-blocking operation that isn't yet ready to complete.

An IOStream's status is only expected to change after a IOStream.Read or IOStream.Write call; don't expect it to change if you just call this query function in a tight loop.

Parameters

context the IOStream to query.

Returns: an IOStatus enum with the current state.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetProperties()

PropertiesRef SDL::IOStream::GetProperties ( ) const

inline

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetSize()

Sint64 SDL::IOStream::GetSize ( ) const

inline

Returns: the size of the data stream in the IOStream on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ GetStatus()

IOStatus SDL::IOStream::GetStatus ( ) const

inline

This information can be useful to decide if a short read or write was due to an error, an EOF, or a non-blocking operation that isn't yet ready to complete.

An IOStream's status is only expected to change after a IOStream.Read or IOStream.Write call; don't expect it to change if you just call this query function in a tight loop.

Returns: an IOStatus enum with the current state.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ IOFromConstMem()

IOStream SDL::IOFromConstMem ( SourceBytes mem )

inline

This function sets up an IOStream struct based on a memory area of a certain size. It assumes the memory area is not writable.

Attempting to write to this IOStream stream will report an error without writing to the memory buffer.

This memory buffer is not copied by the IOStream; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to write to a memory buffer, you should use IOStream.FromMem() with a writable buffer of memory instead.

The following properties will be set at creation time by SDL:

prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a read-only buffer to feed an IOStreamRef stream.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromMem; IOStream.Close; IOStream.Read; IOStream.Seek; IOStream.Tell

◆ IOFromDynamicMem()

IOStream SDL::IOFromDynamicMem ( )

inline

This supports the following properties to provide access to the memory and control over allocations:

prop::IOStream.DYNAMIC_MEMORY_POINTER: a pointer to the internal memory of the stream. This can be set to nullptr to transfer ownership of the memory to the application, which should free the memory with free(). If this is done, the next operation on the stream must be IOStream.Close().
prop::IOStream.DYNAMIC_CHUNKSIZE_NUMBER: memory will be allocated in multiples of this size, defaulting to 1024.

Returns: a pointer to a new IOStream structure or nullptr on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; IOStream.Read; IOStream.Seek; IOStream.Tell; IOStream.Write

◆ IOFromFile()

IOStream SDL::IOFromFile	(	StringParam	file,
		StringParam	mode
	)

inline

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, IOStream.FromFile() can be used to open content:// URIs. As a fallback, IOStream.FromFile() will transparently open a matching filename in the app's assets.

Closing the IOStream will close SDL's internal file handle.

The following properties may be set at creation time by SDL:

prop::IOStream.WINDOWS_HANDLE_POINTER: a pointer, that can be cast to a win32 HANDLE, that this 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.
prop::IOStream.STDIO_FILE_POINTER: a pointer, that can be cast to a stdio FILE *, that this 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.
prop::IOStream.FILE_DESCRIPTOR_NUMBER: a file descriptor that this IOStream is using to access the filesystem.
prop::IOStream.ANDROID_AASSET_POINTER: a pointer, that can be cast to an Android NDK AAsset *, that this IOStream is using to access the filesystem. If SDL used some other method to access the filesystem, this property will not be set.

Parameters

file	a UTF-8 string representing the filename to open.
mode	an ASCII string representing the mode to be used for opening the file.

Returns: a pointer to the IOStream structure that is created or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; IOStream.Flush; IOStream.Read; IOStream.Seek; IOStream.Tell; IOStream.Write

◆ IOFromMem()

IOStream SDL::IOFromMem ( TargetBytes mem )

inline

This function sets up an IOStream struct based on a memory area of a certain size, for both read and write access.

This memory buffer is not copied by the IOStream; the pointer you provide must remain valid until you close the stream. Closing the stream will not free the original buffer.

If you need to make sure the IOStream never writes to the memory buffer, you should use IOStream.FromConstMem() with a read-only buffer of memory instead.

The following properties will be set at creation time by SDL:

prop::IOStream.MEMORY_POINTER: this will be the mem parameter that was passed to this function.
prop::IOStream.MEMORY_SIZE_NUMBER: this will be the size parameter that was passed to this function.

Parameters

mem	a buffer to feed an IOStream stream.

Returns: a valid IOStream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.FromConstMem; IOStream.Close; IOStream.Flush; IOStream.Read; IOStream.Seek; IOStream.Tell; IOStream.Write

◆ IOprintf()

size_t SDL::IOprintf	(	IOStreamParam	context,
		SDL_PRINTF_FORMAT_STRING const char *	fmt,
			...
	)

inline

Warning: this is not typesafe! Prefer using print() and println()

This function does formatted printing to the stream.

Parameters

context	a pointer to an IOStream structure.
fmt	a printf() style format string.
...	additional parameters matching % tokens in the `fmt` string, if any.

Returns: the number of bytes written or 0 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.vprintf; IOStream.Write

◆ IOvprintf()

size_t SDL::IOvprintf	(	IOStreamParam	context,
		SDL_PRINTF_FORMAT_STRING const char *	fmt,
		va_list	ap
	)

inline

This function does formatted printing to the stream.

Parameters

context	a pointer to an IOStream structure.
fmt	a printf() style format string.
ap	a variable argument list.

Returns: the number of bytes written or 0 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.printf; IOStream.Write

◆ LoadFile() [1/3]

StringResult SDL::IOStream::LoadFile ( )

inline

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported on the returned string.

Returns: the data in bytes

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadFile; IOStream.SaveFile

◆ LoadFile() [2/3]

StringResult SDL::LoadFile	(	IOStreamParam	src,
		bool	closeio = `true`
	)

inline

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported on the returned string.

The data should be freed with free().

Parameters

src	the IOStream to read all available data from.
closeio	if true, calls IOStream.Close() on `src` before returning, even in the case of an error.

Returns: the data or nullptr on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: LoadFile; IOStream.SaveFile

◆ LoadFile() [3/3]

StringResult SDL::LoadFile ( StringParam file )

inline

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported on the returned string.

Parameters

file	the path to read all available data from.

Returns: the data.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.LoadFile; SaveFile

◆ LoadFileAs()

template<class T >

OwnArray< T > SDL::LoadFileAs ( StringParam file )

inline

The data is allocated with a zero byte at the end (null terminated) for convenience. This extra byte is not included in the value reported on the returned string.

Parameters

file	the path to read all available data from.

Returns: the data.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.LoadFile; SaveFile

◆ Open()

IOStream SDL::IOStream::Open	(	const IOStreamInterface &	iface,
		void *	userdata
	)

inlinestatic

Applications do not need to use this function unless they are providing their own IOStream implementation. If you just need an IOStream to read/write a common data source, you should use the built-in implementations in SDL, like IOStream.FromFile() or IOStream.FromMem(), etc.

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 IOStream, initialized using InitInterface().
userdata	the pointer that will be passed to the interface functions.

Returns: a valid stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; InitInterface; IOStream.FromConstMem; IOStream.FromFile; IOStream.FromMem

◆ OpenIO()

IOStream SDL::OpenIO	(	const IOStreamInterface &	iface,
		void *	userdata
	)

inline

Applications do not need to use this function unless they are providing their own IOStream implementation. If you just need an IOStream to read/write a common data source, you should use the built-in implementations in SDL, like IOStream.FromFile() or IOStream.FromMem(), etc.

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 IOStream, initialized using InitInterface().
userdata	the pointer that will be passed to the interface functions.

Returns: a pointer to the allocated memory on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Close; InitInterface; IOStream.FromConstMem; IOStream.FromFile; IOStream.FromMem

◆ Read()

size_t SDL::IOStream::Read ( TargetBytes buf )

inline

This function reads up size bytes from the data source to the area pointed at by ptr. This function may read less bytes than requested.

This function will return zero when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If zero is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

buf	a pointer to a buffer to read data into.

Returns: the number of bytes read, or 0 on end of file or other failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Write; IOStream.GetStatus

◆ ReadIO()

size_t SDL::ReadIO	(	IOStreamParam	context,
		TargetBytes	buf
	)

inline

This function reads up size bytes from the data source to the area pointed at by ptr. This function may read less bytes than requested.

This function will return zero when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If zero is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

context	a pointer to an IOStream structure.
buf	a pointer to a buffer to read data into.

Returns: the number of bytes read, or 0 on end of file or other failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Write; IOStream.GetStatus

◆ ReadS16BE() [1/2]

Sint16 SDL::IOStream::ReadS16BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS16BE() [2/2]

Sint16 SDL::ReadS16BE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS16LE() [1/2]

Sint16 SDL::IOStream::ReadS16LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS16LE() [2/2]

Sint16 SDL::ReadS16LE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS32BE() [1/2]

Sint32 SDL::IOStream::ReadS32BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS32BE() [2/2]

Sint32 SDL::ReadS32BE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS32LE() [1/2]

Sint32 SDL::IOStream::ReadS32LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS32LE() [2/2]

Sint32 SDL::ReadS32LE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS64BE() [1/2]

Sint64 SDL::IOStream::ReadS64BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS64BE() [2/2]

Sint64 SDL::ReadS64BE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS64LE() [1/2]

Sint64 SDL::IOStream::ReadS64LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS64LE() [2/2]

Sint64 SDL::ReadS64LE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadS8()

Sint8 SDL::ReadS8 ( IOStreamParam src )

inline

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the IOStream to read from.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU16BE() [1/2]

Uint16 SDL::IOStream::ReadU16BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU16BE() [2/2]

Uint16 SDL::ReadU16BE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU16LE() [1/2]

Uint16 SDL::IOStream::ReadU16LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU16LE() [2/2]

Uint16 SDL::ReadU16LE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU32BE() [1/2]

Uint32 SDL::IOStream::ReadU32BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU32BE() [2/2]

Uint32 SDL::ReadU32BE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU32LE() [1/2]

Uint32 SDL::IOStream::ReadU32LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU32LE() [2/2]

Uint32 SDL::ReadU32LE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU64BE() [1/2]

Uint64 SDL::IOStream::ReadU64BE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU64BE() [2/2]

Uint64 SDL::ReadU64BE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU64LE() [1/2]

Uint64 SDL::IOStream::ReadU64LE ( )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Returns: the data read on success.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU64LE() [2/2]

Uint64 SDL::ReadU64LE ( IOStreamParam src )

inline

SDL byteswaps the data only if necessary, so the data returned will be in the native byte order.

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the stream from which to read data.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ ReadU8()

Uint8 SDL::ReadU8 ( IOStreamParam src )

inline

This function will return false when the data stream is completely read, and IOStream.GetStatus() will return IO_STATUS_EOF. If false is returned and the stream is not at EOF, IOStream.GetStatus() will return a different error value and GetError() will offer a human-readable message.

Parameters

src	the IOStream to read from.

Returns: the data read.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ SaveFile() [1/3]

void SDL::SaveFile	(	IOStreamParam	src,
		SourceBytes	data,
		bool	closeio = `false`
	)

inline

Parameters

src	the IOStream to write all data to.
data	the data to be written.
closeio	if true, calls IOStream.Close() on `src` before returning, even in the case of an error.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SaveFile; IOStream.LoadFile

◆ SaveFile() [2/3]

void SDL::IOStream::SaveFile ( SourceBytes data )

inline

Parameters

data	the data to be written. If datasize is 0, may be nullptr or a invalid pointer.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: SaveFile; IOStream.LoadFile

◆ SaveFile() [3/3]

void SDL::SaveFile	(	StringParam	file,
		SourceBytes	data
	)

inline

Parameters

file	the path to write all available data into.
data	the data to be written.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.SaveFile; LoadFile

◆ Seek()

Sint64 SDL::IOStream::Seek	(	Sint64	offset,
		IOWhence	whence
	)

inline

This function seeks to byte offset, relative to whence.

whence may be any of the following values:

IO_SEEK_SET: seek from the beginning of data
IO_SEEK_CUR: seek relative to current read point
IO_SEEK_END: seek relative to the end of data

If this stream can not seek, it will return -1.

Parameters

offset	an offset in bytes, relative to `whence` location; can be negative.
whence	any of `IO_SEEK_SET`, `IO_SEEK_CUR`, `IO_SEEK_END`.

Returns: the final offset in the data stream after the seek or -1 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Tell

◆ SeekIO()

Sint64 SDL::SeekIO	(	IOStreamParam	context,
		Sint64	offset,
		IOWhence	whence
	)

inline

This function seeks to byte offset, relative to whence.

whence may be any of the following values:

IO_SEEK_SET: seek from the beginning of data
IO_SEEK_CUR: seek relative to current read point
IO_SEEK_END: seek relative to the end of data

If this stream can not seek, it will return -1.

Parameters

context	a pointer to an IOStream structure.
offset	an offset in bytes, relative to `whence` location; can be negative.
whence	any of `IO_SEEK_SET`, `IO_SEEK_CUR`, `IO_SEEK_END`.

Returns: the final offset in the data stream after the seek or -1 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Tell

◆ Tell()

Sint64 SDL::IOStream::Tell ( ) const

inline

IOStream.Tell is actually a wrapper function that calls the IOStream's seek method, with an offset of 0 bytes from IO_SEEK_CUR, to simplify application development.

Returns: the current offset in the stream, or -1 if the information can not be determined.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Seek

◆ TellIO()

Sint64 SDL::TellIO ( IOStreamParam context )

inline

IOStream.Tell is actually a wrapper function that calls the IOStream's seek method, with an offset of 0 bytes from IO_SEEK_CUR, to simplify application development.

Parameters

context an IOStream data stream object from which to get the current offset.

Returns: the current offset in the stream, or -1 if the information can not be determined.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.Seek

◆ vprintf()

size_t SDL::IOStream::vprintf	(	SDL_PRINTF_FORMAT_STRING const char *	fmt,
		va_list	ap
	)

inline

Warning: this is not typesafe! Prefer using print() and println()

This function does formatted printing to the stream.

Parameters

fmt	a printf() style format string.
ap	a variable argument list.

Returns: the number of bytes written or 0 on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.printf; IOStream.Write

◆ Write()

size_t SDL::IOStream::Write ( SourceBytes buf )

inline

This function writes exactly size bytes from the area pointed at by ptr to the stream. If this fails for any reason, it'll return less than size to demonstrate how far the write progressed. On success, it returns size.

On error, this function still attempts to write as much as possible, so it might return a positive value less than the requested write size.

The caller can use IOStream.GetStatus() to determine if the problem is recoverable, such as a non-blocking write that can simply be retried later, or a fatal error.

Parameters

buf	the bytes to write to

Returns: the number of bytes written, which will be less than size on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.printf; IOStream.Read; IOStream.Seek; IOStream.Flush; IOStream.GetStatus

◆ WriteIO()

size_t SDL::WriteIO	(	IOStreamParam	context,
		SourceBytes	buf
	)

inline

This function writes exactly size bytes from the area pointed at by ptr to the stream. If this fails for any reason, it'll return less than size to demonstrate how far the write progressed. On success, it returns size.

On error, this function still attempts to write as much as possible, so it might return a positive value less than the requested write size.

The caller can use IOStream.GetStatus() to determine if the problem is recoverable, such as a non-blocking write that can simply be retried later, or a fatal error.

Parameters

context	a pointer to an IOStream structure.
buf	a pointer to a buffer containing data to write.

Returns: the number of bytes written, which will be less than size on failure; call GetError() for more information.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: IOStream.printf; IOStream.Read; IOStream.Seek; IOStream.Flush; IOStream.GetStatus

◆ WriteS16BE() [1/2]

void SDL::WriteS16BE	(	IOStreamParam	dst,
		Sint16	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS16BE() [2/2]

void SDL::IOStream::WriteS16BE ( Sint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS16LE() [1/2]

void SDL::WriteS16LE	(	IOStreamParam	dst,
		Sint16	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS16LE() [2/2]

void SDL::IOStream::WriteS16LE ( Sint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS32BE() [1/2]

void SDL::WriteS32BE	(	IOStreamParam	dst,
		Sint32	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS32BE() [2/2]

void SDL::IOStream::WriteS32BE ( Sint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS32LE() [1/2]

void SDL::WriteS32LE	(	IOStreamParam	dst,
		Sint32	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS32LE() [2/2]

void SDL::IOStream::WriteS32LE ( Sint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS64BE() [1/2]

void SDL::WriteS64BE	(	IOStreamParam	dst,
		Sint64	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS64BE() [2/2]

void SDL::IOStream::WriteS64BE ( Sint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS64LE() [1/2]

void SDL::WriteS64LE	(	IOStreamParam	dst,
		Sint64	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS64LE() [2/2]

void SDL::IOStream::WriteS64LE ( Sint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS8() [1/2]

void SDL::WriteS8	(	IOStreamParam	dst,
		Sint8	value
	)

inline

Parameters

dst	the IOStream to write to.
value	the byte value to write.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteS8() [2/2]

void SDL::IOStream::WriteS8 ( Sint8 value )

inline

Parameters

value the byte value to write.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU16BE() [1/2]

void SDL::WriteU16BE	(	IOStreamParam	dst,
		Uint16	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU16BE() [2/2]

void SDL::IOStream::WriteU16BE ( Uint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU16LE() [1/2]

void SDL::WriteU16LE	(	IOStreamParam	dst,
		Uint16	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU16LE() [2/2]

void SDL::IOStream::WriteU16LE ( Uint16 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU32BE() [1/2]

void SDL::WriteU32BE	(	IOStreamParam	dst,
		Uint32	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU32BE() [2/2]

void SDL::IOStream::WriteU32BE ( Uint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU32LE() [1/2]

void SDL::WriteU32LE	(	IOStreamParam	dst,
		Uint32	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU32LE() [2/2]

void SDL::IOStream::WriteU32LE ( Uint32 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU64BE() [1/2]

void SDL::WriteU64BE	(	IOStreamParam	dst,
		Uint64	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU64BE() [2/2]

void SDL::IOStream::WriteU64BE ( Uint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in big-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU64LE() [1/2]

void SDL::WriteU64LE	(	IOStreamParam	dst,
		Uint64	value
	)

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

dst	the stream to which data will be written.
value	the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU64LE() [2/2]

void SDL::IOStream::WriteU64LE ( Uint64 value )

inline

SDL byteswaps the data only if necessary, so the application always specifies native format, and the data written will be in little-endian format.

Parameters

value the data to be written, in native format.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU8() [1/2]

void SDL::WriteU8	(	IOStreamParam	dst,
		Uint8	value
	)

inline

Parameters

dst	the IOStream to write to.
value	the byte value to write.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

◆ WriteU8() [2/2]

void SDL::IOStream::WriteU8 ( Uint8 value )

inline

Parameters

value the byte value to write.

Exceptions

Error on failure.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

SDL_IO_STATUS_WRITEONLY

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ IOStatus

◆ IOStreamInterface

◆ IOWhence

Function Documentation

◆ Close()

◆ CloseIO()

◆ Flush()

◆ FlushIO()

◆ FromConstMem()

◆ FromDynamicMem()

◆ FromFile()

◆ FromMem()

◆ GetIOProperties()

◆ GetIOSize()

◆ GetIOStatus()

◆ GetProperties()

◆ GetSize()

◆ GetStatus()

◆ IOFromConstMem()

◆ IOFromDynamicMem()

◆ IOFromFile()

◆ IOFromMem()

◆ IOprintf()

◆ IOvprintf()

◆ LoadFile() [1/3]

◆ LoadFile() [2/3]

◆ LoadFile() [3/3]

◆ LoadFileAs()

◆ Open()

◆ OpenIO()

◆ Read()

◆ ReadIO()

◆ ReadS16BE() [1/2]

◆ ReadS16BE() [2/2]

◆ ReadS16LE() [1/2]

◆ ReadS16LE() [2/2]

◆ ReadS32BE() [1/2]

◆ ReadS32BE() [2/2]

◆ ReadS32LE() [1/2]

◆ ReadS32LE() [2/2]

◆ ReadS64BE() [1/2]

◆ ReadS64BE() [2/2]

◆ ReadS64LE() [1/2]

◆ ReadS64LE() [2/2]

◆ ReadS8()

◆ ReadU16BE() [1/2]

◆ ReadU16BE() [2/2]

◆ ReadU16LE() [1/2]

◆ ReadU16LE() [2/2]

◆ ReadU32BE() [1/2]

◆ ReadU32BE() [2/2]

◆ ReadU32LE() [1/2]

◆ ReadU32LE() [2/2]

◆ ReadU64BE() [1/2]

◆ ReadU64BE() [2/2]

◆ ReadU64LE() [1/2]

◆ ReadU64LE() [2/2]

◆ ReadU8()

◆ SaveFile() [1/3]

◆ SaveFile() [2/3]

◆ SaveFile() [3/3]

◆ Seek()

◆ SeekIO()

◆ Tell()

◆ TellIO()

◆ vprintf()

◆ Write()

◆ WriteIO()

◆ WriteS16BE() [1/2]

◆ WriteS16BE() [2/2]

◆ WriteS16LE() [1/2]

◆ WriteS16LE() [2/2]

◆ WriteS32BE() [1/2]

◆ WriteS32BE() [2/2]