Added SDL_FlushIO()

Also added SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER and refactored the internal API to be able to create SDL_IOStream objects from native file handles.

include/SDL3/SDL_iostream.h

@@ -133,6 +133,17 @@ typedef struct SDL_IOStreamInterface
      */
     size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status);
 
+    /**
+     *  If the stream is buffering, make sure the data is written out.
+     *
+     *  On failure, you should set `*status` to a value from the
+     *  SDL_IOStatus enum. You do not have to explicitly set this on
+     *  a successful flush.
+     *
+     *  \return SDL_TRUE if successful or SDL_FALSE on write error when flushing data.
+     */
+    SDL_bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status);
+
     /**
      *  Close and free any allocated resources.
      *
@@ -152,8 +163,8 @@ typedef struct SDL_IOStreamInterface
  * the code using this interface should be updated to handle the old version.
  */
 SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE,
-    (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 24) ||
-    (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 48));
+    (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) ||
+    (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56));
 
 /**
  * The read/write operation structure.
@@ -233,6 +244,7 @@ typedef struct SDL_IOStream SDL_IOStream;
  *   than your app, trying to use this pointer will almost certainly result in
  *   a crash! This is mostly a problem on Windows; make sure you build SDL and
  *   your app with the same compiler and settings to avoid it.
+ * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this SDL_IOStream is using to access the filesystem.
  * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast
  *   to an Android NDK `AAsset *`, that this SDL_IOStream is using to access
  *   the filesystem. If SDL used some other method to access the filesystem,
@@ -247,6 +259,7 @@ typedef struct SDL_IOStream SDL_IOStream;
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_CloseIO
+ * \sa SDL_FlushIO
  * \sa SDL_ReadIO
  * \sa SDL_SeekIO
  * \sa SDL_TellIO
@@ -256,6 +269,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons
 
 #define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER    "SDL.iostream.windows.handle"
 #define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER        "SDL.iostream.stdio.file"
+#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER    "SDL.iostream.file_descriptor"
 #define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER    "SDL.iostream.android.aasset"
 
 /**
@@ -282,6 +296,7 @@ extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, cons
  *
  * \sa SDL_IOFromConstMem
  * \sa SDL_CloseIO
+ * \sa SDL_FlushIO
  * \sa SDL_ReadIO
  * \sa SDL_SeekIO
  * \sa SDL_TellIO
@@ -465,8 +480,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context);
  *               negative.
  * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`,
  *               `SDL_IO_SEEK_END`.
- * \returns the final offset in the data stream after the seek or a negative
- *          error code on failure; call SDL_GetError() for more information.
+ * \returns the final offset in the data stream after the seek or -1 on failure; call SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -539,6 +553,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr,
  * \sa SDL_IOprintf
  * \sa SDL_ReadIO
  * \sa SDL_SeekIO
+ * \sa SDL_FlushIO
  * \sa SDL_GetIOStatus
  */
 extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size);
@@ -580,6 +595,22 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT
  */
 extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
 
+/**
+ * Flush any buffered data in the stream.
+ *
+ * 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.
+ *
+ * \param context SDL_IOStream structure to flush.
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_OpenIO
+ * \sa SDL_WriteIO
+ */
+extern SDL_DECLSPEC SDL_bool SDLCALL SDL_FlushIO(SDL_IOStream *context);
+
 /**
  * Load all the data from an SDL data stream.
  *
@@ -590,7 +621,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
  * The data should be freed with SDL_free().
  *
  * \param src the SDL_IOStream to read all available data from.
- * \param datasize if not NULL, will store the number of bytes read.
+ * \param datasize a pointer filled in with the number of bytes read, may be NULL.
  * \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
  *                even in the case of an error.
  * \returns the data or NULL on failure; call SDL_GetError() for more