From 95c8a1cf7c34630dc922ad1e012f41e6ca8eab90 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Wed, 13 Nov 2024 20:10:58 -0500
Subject: [PATCH] iostream: Update docs about return values and
SDL_GetIOStatus().
Fixes #11395.
---
include/SDL3/SDL_iostream.h | 82 ++++++++++++++++++++++++++++++++++---
1 file changed, 77 insertions(+), 5 deletions(-)
diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h
index 9ee15f1f1293d..cca2f662e351c 100644
--- a/include/SDL3/SDL_iostream.h
+++ b/include/SDL3/SDL_iostream.h
@@ -541,10 +541,12 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
* Read from a data source.
*
* 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. It
- * will return zero when the data stream is completely read, and
- * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF, or on error, and
- * SDL_GetIOStatus() will return SDL_IO_STATUS_ERROR.
+ * 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
*
* \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer to read data into.
@@ -735,9 +737,14 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data
/**
* Use this function to read a byte from an SDL_IOStream.
*
+ * This function will return false when the data stream is completely read,
+ * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the SDL_IOStream to read from.
* \param value a pointer filled in with the data read.
- * \returns true on success or false on failure; call SDL_GetError() for more
+ * \returns true on success or false on failure or EOF; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.1.3.
@@ -747,6 +754,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value);
/**
* Use this function to read a signed byte from an SDL_IOStream.
*
+ * This function will return false when the data stream is completely read,
+ * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the SDL_IOStream to read from.
* \param value a pointer filled in with the data read.
* \returns true on success or false on failure; call SDL_GetError() for more
@@ -763,6 +775,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value);
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -779,6 +796,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -795,6 +817,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -811,6 +838,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -827,6 +859,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -843,6 +880,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -859,6 +901,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -875,6 +922,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -891,6 +943,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -907,6 +964,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -923,6 +985,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()
@@ -939,6 +1006,11 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value)
* 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 SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
+ * and the stream is not at EOF, SDL_GetIOStatus() will return a different
+ * error value and SDL_GetError() will offer a human-readable message.
+ *
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns true on successful write or false on failure; call SDL_GetError()