eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-25 14:09:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions2

iostream: Update docs about return values and SDL_GetIOStatus().

Browse source 
Fixes .
This commit is contained in:
Ryan C. Gordon 2024-11-13 20:10:58 -05:00
parent 7007b4762b
commit 95c8a1cf7c
No known key found for this signature in database
GPG key ID: FA148B892AB48044
1 changed files with 77 additions and 5 deletions

82
include/SDL3/SDL_iostream.h
View file

@ -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()