SDL 3.0
SDL_iostream.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/* WIKI CATEGORY: IOStream */
23
24/**
25 * # CategoryIOStream
26 *
27 * SDL provides an abstract interface for reading and writing data streams. It
28 * offers implementations for files, memory, etc, and the app can provideo
29 * their own implementations, too.
30 *
31 * SDL_IOStream is not related to the standard C++ iostream class, other than
32 * both are abstract interfaces to read/write data.
33 */
34
35#ifndef SDL_iostream_h_
36#define SDL_iostream_h_
37
38#include <SDL3/SDL_stdinc.h>
39#include <SDL3/SDL_error.h>
40#include <SDL3/SDL_properties.h>
41
42#include <SDL3/SDL_begin_code.h>
43/* Set up for C function definitions, even when using C++ */
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/**
49 * SDL_IOStream status, set by a read or write operation.
50 *
51 * \since This enum is available since SDL 3.1.3.
52 */
53typedef enum SDL_IOStatus
54{
55 SDL_IO_STATUS_READY, /**< Everything is ready (no errors and not EOF). */
56 SDL_IO_STATUS_ERROR, /**< Read or write I/O error */
57 SDL_IO_STATUS_EOF, /**< End of file */
58 SDL_IO_STATUS_NOT_READY, /**< Non blocking I/O, not ready */
59 SDL_IO_STATUS_READONLY, /**< Tried to write a read-only buffer */
60 SDL_IO_STATUS_WRITEONLY /**< Tried to read a write-only buffer */
62
63/**
64 * Possible `whence` values for SDL_IOStream seeking.
65 *
66 * These map to the same "whence" concept that `fseek` or `lseek` use in the
67 * standard C runtime.
68 *
69 * \since This enum is available since SDL 3.1.3.
70 */
71typedef enum SDL_IOWhence
72{
73 SDL_IO_SEEK_SET, /**< Seek from the beginning of data */
74 SDL_IO_SEEK_CUR, /**< Seek relative to current read point */
75 SDL_IO_SEEK_END /**< Seek relative to the end of data */
77
78/**
79 * The function pointers that drive an SDL_IOStream.
80 *
81 * Applications can provide this struct to SDL_OpenIO() to create their own
82 * implementation of SDL_IOStream. This is not necessarily required, as SDL
83 * already offers several common types of I/O streams, via functions like
84 * SDL_IOFromFile() and SDL_IOFromMem().
85 *
86 * This structure should be initialized using SDL_INIT_INTERFACE()
87 *
88 * \since This struct is available since SDL 3.1.3.
89 *
90 * \sa SDL_INIT_INTERFACE
91 */
93{
94 /* The version of this interface */
96
97 /**
98 * Return the number of bytes in this SDL_IOStream
99 *
100 * \return the total size of the data stream, or -1 on error.
101 */
102 Sint64 (SDLCALL *size)(void *userdata);
103
104 /**
105 * Seek to `offset` relative to `whence`, one of stdio's whence values:
106 * SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END
107 *
108 * \return the final offset in the data stream, or -1 on error.
109 */
110 Sint64 (SDLCALL *seek)(void *userdata, Sint64 offset, SDL_IOWhence whence);
111
112 /**
113 * Read up to `size` bytes from the data stream to the area pointed
114 * at by `ptr`.
115 *
116 * On an incomplete read, you should set `*status` to a value from the
117 * SDL_IOStatus enum. You do not have to explicitly set this on
118 * a complete, successful read.
119 *
120 * \return the number of bytes read
121 */
122 size_t (SDLCALL *read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status);
123
124 /**
125 * Write exactly `size` bytes from the area pointed at by `ptr`
126 * to data stream.
127 *
128 * On an incomplete write, you should set `*status` to a value from the
129 * SDL_IOStatus enum. You do not have to explicitly set this on
130 * a complete, successful write.
131 *
132 * \return the number of bytes written
133 */
134 size_t (SDLCALL *write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status);
135
136 /**
137 * If the stream is buffering, make sure the data is written out.
138 *
139 * On failure, you should set `*status` to a value from the
140 * SDL_IOStatus enum. You do not have to explicitly set this on
141 * a successful flush.
142 *
143 * \return true if successful or false on write error when flushing data.
144 */
145 bool (SDLCALL *flush)(void *userdata, SDL_IOStatus *status);
146
147 /**
148 * Close and free any allocated resources.
149 *
150 * This does not guarantee file writes will sync to physical media; they
151 * can be in the system's file cache, waiting to go to disk.
152 *
153 * The SDL_IOStream is still destroyed even if this fails, so clean up anything
154 * even if flushing buffers, etc, returns an error.
155 *
156 * \return true if successful or false on write error when flushing data.
157 */
158 bool (SDLCALL *close)(void *userdata);
159
161
162/* Check the size of SDL_IOStreamInterface
163 *
164 * If this assert fails, either the compiler is padding to an unexpected size,
165 * or the interface has been updated and this should be updated to match and
166 * the code using this interface should be updated to handle the old version.
167 */
168SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE,
169 (sizeof(void *) == 4 && sizeof(SDL_IOStreamInterface) == 28) ||
170 (sizeof(void *) == 8 && sizeof(SDL_IOStreamInterface) == 56));
171
172/**
173 * The read/write operation structure.
174 *
175 * This operates as an opaque handle. There are several APIs to create various
176 * types of I/O streams, or an app can supply an SDL_IOStreamInterface to
177 * SDL_OpenIO() to provide their own stream implementation behind this
178 * struct's abstract interface.
179 *
180 * \since This struct is available since SDL 3.1.3.
181 */
183
184
185/**
186 * \name IOFrom functions
187 *
188 * Functions to create SDL_IOStream structures from various data streams.
189 */
190/* @{ */
191
192/**
193 * Use this function to create a new SDL_IOStream structure for reading from
194 * and/or writing to a named file.
195 *
196 * The `mode` string is treated roughly the same as in a call to the C
197 * library's fopen(), even if SDL doesn't happen to use fopen() behind the
198 * scenes.
199 *
200 * Available `mode` strings:
201 *
202 * - "r": Open a file for reading. The file must exist.
203 * - "w": Create an empty file for writing. If a file with the same name
204 * already exists its content is erased and the file is treated as a new
205 * empty file.
206 * - "a": Append to a file. Writing operations append data at the end of the
207 * file. The file is created if it does not exist.
208 * - "r+": Open a file for update both reading and writing. The file must
209 * exist.
210 * - "w+": Create an empty file for both reading and writing. If a file with
211 * the same name already exists its content is erased and the file is
212 * treated as a new empty file.
213 * - "a+": Open a file for reading and appending. All writing operations are
214 * performed at the end of the file, protecting the previous content to be
215 * overwritten. You can reposition (fseek, rewind) the internal pointer to
216 * anywhere in the file for reading, but writing operations will move it
217 * back to the end of file. The file is created if it does not exist.
218 *
219 * **NOTE**: In order to open a file as a binary file, a "b" character has to
220 * be included in the `mode` string. This additional "b" character can either
221 * be appended at the end of the string (thus making the following compound
222 * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the
223 * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+").
224 * Additional characters may follow the sequence, although they should have no
225 * effect. For example, "t" is sometimes appended to make explicit the file is
226 * a text file.
227 *
228 * This function supports Unicode filenames, but they must be encoded in UTF-8
229 * format, regardless of the underlying operating system.
230 *
231 * In Android, SDL_IOFromFile() can be used to open content:// URIs. As a
232 * fallback, SDL_IOFromFile() will transparently open a matching filename in
233 * the app's `assets`.
234 *
235 * Closing the SDL_IOStream will close SDL's internal file handle.
236 *
237 * The following properties may be set at creation time by SDL:
238 *
239 * - `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER`: a pointer, that can be cast
240 * to a win32 `HANDLE`, that this SDL_IOStream is using to access the
241 * filesystem. If the program isn't running on Windows, or SDL used some
242 * other method to access the filesystem, this property will not be set.
243 * - `SDL_PROP_IOSTREAM_STDIO_FILE_POINTER`: a pointer, that can be cast to a
244 * stdio `FILE *`, that this SDL_IOStream is using to access the filesystem.
245 * If SDL used some other method to access the filesystem, this property
246 * will not be set. PLEASE NOTE that if SDL is using a different C runtime
247 * than your app, trying to use this pointer will almost certainly result in
248 * a crash! This is mostly a problem on Windows; make sure you build SDL and
249 * your app with the same compiler and settings to avoid it.
250 * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this
251 * SDL_IOStream is using to access the filesystem.
252 * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a pointer, that can be cast
253 * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access
254 * the filesystem. If SDL used some other method to access the filesystem,
255 * this property will not be set.
256 *
257 * \param file a UTF-8 string representing the filename to open.
258 * \param mode an ASCII string representing the mode to be used for opening
259 * the file.
260 * \returns a pointer to the SDL_IOStream structure that is created or NULL on
261 * failure; call SDL_GetError() for more information.
262 *
263 * \since This function is available since SDL 3.1.3.
264 *
265 * \sa SDL_CloseIO
266 * \sa SDL_FlushIO
267 * \sa SDL_ReadIO
268 * \sa SDL_SeekIO
269 * \sa SDL_TellIO
270 * \sa SDL_WriteIO
271 */
272extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromFile(const char *file, const char *mode);
273
274#define SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER "SDL.iostream.windows.handle"
275#define SDL_PROP_IOSTREAM_STDIO_FILE_POINTER "SDL.iostream.stdio.file"
276#define SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER "SDL.iostream.file_descriptor"
277#define SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER "SDL.iostream.android.aasset"
278
279/**
280 * Use this function to prepare a read-write memory buffer for use with
281 * SDL_IOStream.
282 *
283 * This function sets up an SDL_IOStream struct based on a memory area of a
284 * certain size, for both read and write access.
285 *
286 * This memory buffer is not copied by the SDL_IOStream; the pointer you
287 * provide must remain valid until you close the stream. Closing the stream
288 * will not free the original buffer.
289 *
290 * If you need to make sure the SDL_IOStream never writes to the memory
291 * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of
292 * memory instead.
293 *
294 * The following properties will be set at creation time by SDL:
295 *
296 * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that
297 * was passed to this function.
298 * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter
299 * that was passed to this function.
300 *
301 * \param mem a pointer to a buffer to feed an SDL_IOStream stream.
302 * \param size the buffer size, in bytes.
303 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
304 * SDL_GetError() for more information.
305 *
306 * \since This function is available since SDL 3.1.3.
307 *
308 * \sa SDL_IOFromConstMem
309 * \sa SDL_CloseIO
310 * \sa SDL_FlushIO
311 * \sa SDL_ReadIO
312 * \sa SDL_SeekIO
313 * \sa SDL_TellIO
314 * \sa SDL_WriteIO
315 */
316extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromMem(void *mem, size_t size);
317
318#define SDL_PROP_IOSTREAM_MEMORY_POINTER "SDL.iostream.memory.base"
319#define SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER "SDL.iostream.memory.size"
320
321/**
322 * Use this function to prepare a read-only memory buffer for use with
323 * SDL_IOStream.
324 *
325 * This function sets up an SDL_IOStream struct based on a memory area of a
326 * certain size. It assumes the memory area is not writable.
327 *
328 * Attempting to write to this SDL_IOStream stream will report an error
329 * without writing to the memory buffer.
330 *
331 * This memory buffer is not copied by the SDL_IOStream; the pointer you
332 * provide must remain valid until you close the stream. Closing the stream
333 * will not free the original buffer.
334 *
335 * If you need to write to a memory buffer, you should use SDL_IOFromMem()
336 * with a writable buffer of memory instead.
337 *
338 * The following properties will be set at creation time by SDL:
339 *
340 * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that
341 * was passed to this function.
342 * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter
343 * that was passed to this function.
344 *
345 * \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
346 * \param size the buffer size, in bytes.
347 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
348 * SDL_GetError() for more information.
349 *
350 * \since This function is available since SDL 3.1.3.
351 *
352 * \sa SDL_IOFromMem
353 * \sa SDL_CloseIO
354 * \sa SDL_ReadIO
355 * \sa SDL_SeekIO
356 * \sa SDL_TellIO
357 */
358extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromConstMem(const void *mem, size_t size);
359
360/**
361 * Use this function to create an SDL_IOStream that is backed by dynamically
362 * allocated memory.
363 *
364 * This supports the following properties to provide access to the memory and
365 * control over allocations:
366 *
367 * - `SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER`: a pointer to the internal
368 * memory of the stream. This can be set to NULL to transfer ownership of
369 * the memory to the application, which should free the memory with
370 * SDL_free(). If this is done, the next operation on the stream must be
371 * SDL_CloseIO().
372 * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in
373 * multiples of this size, defaulting to 1024.
374 *
375 * \returns a pointer to a new SDL_IOStream structure or NULL on failure; call
376 * SDL_GetError() for more information.
377 *
378 * \since This function is available since SDL 3.1.3.
379 *
380 * \sa SDL_CloseIO
381 * \sa SDL_ReadIO
382 * \sa SDL_SeekIO
383 * \sa SDL_TellIO
384 * \sa SDL_WriteIO
385 */
386extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_IOFromDynamicMem(void);
387
388#define SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER "SDL.iostream.dynamic.memory"
389#define SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER "SDL.iostream.dynamic.chunksize"
390
391/* @} *//* IOFrom functions */
392
393
394/**
395 * Create a custom SDL_IOStream.
396 *
397 * Applications do not need to use this function unless they are providing
398 * their own SDL_IOStream implementation. If you just need an SDL_IOStream to
399 * read/write a common data source, you should use the built-in
400 * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc.
401 *
402 * This function makes a copy of `iface` and the caller does not need to keep
403 * it around after this call.
404 *
405 * \param iface the interface that implements this SDL_IOStream, initialized
406 * using SDL_INIT_INTERFACE().
407 * \param userdata the pointer that will be passed to the interface functions.
408 * \returns a pointer to the allocated memory on success or NULL on failure;
409 * call SDL_GetError() for more information.
410 *
411 * \since This function is available since SDL 3.1.3.
412 *
413 * \sa SDL_CloseIO
414 * \sa SDL_INIT_INTERFACE
415 * \sa SDL_IOFromConstMem
416 * \sa SDL_IOFromFile
417 * \sa SDL_IOFromMem
418 */
419extern SDL_DECLSPEC SDL_IOStream * SDLCALL SDL_OpenIO(const SDL_IOStreamInterface *iface, void *userdata);
420
421/**
422 * Close and free an allocated SDL_IOStream structure.
423 *
424 * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any
425 * resources used by the stream and frees the SDL_IOStream itself. This
426 * returns true on success, or false if the stream failed to flush to its
427 * output (e.g. to disk).
428 *
429 * Note that if this fails to flush the stream for any reason, this function
430 * reports an error, but the SDL_IOStream is still invalid once this function
431 * returns.
432 *
433 * This call flushes any buffered writes to the operating system, but there
434 * are no guarantees that those writes have gone to physical media; they might
435 * be in the OS's file cache, waiting to go to disk later. If it's absolutely
436 * crucial that writes go to disk immediately, so they are definitely stored
437 * even if the power fails before the file cache would have caught up, one
438 * should call SDL_FlushIO() before closing. Note that flushing takes time and
439 * makes the system and your app operate less efficiently, so do so sparingly.
440 *
441 * \param context SDL_IOStream structure to close.
442 * \returns true on success or false on failure; call SDL_GetError() for more
443 * information.
444 *
445 * \since This function is available since SDL 3.1.3.
446 *
447 * \sa SDL_OpenIO
448 */
449extern SDL_DECLSPEC bool SDLCALL SDL_CloseIO(SDL_IOStream *context);
450
451/**
452 * Get the properties associated with an SDL_IOStream.
453 *
454 * \param context a pointer to an SDL_IOStream structure.
455 * \returns a valid property ID on success or 0 on failure; call
456 * SDL_GetError() for more information.
457 *
458 * \since This function is available since SDL 3.1.3.
459 */
460extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetIOProperties(SDL_IOStream *context);
461
462/**
463 * Query the stream status of an SDL_IOStream.
464 *
465 * This information can be useful to decide if a short read or write was due
466 * to an error, an EOF, or a non-blocking operation that isn't yet ready to
467 * complete.
468 *
469 * An SDL_IOStream's status is only expected to change after a SDL_ReadIO or
470 * SDL_WriteIO call; don't expect it to change if you just call this query
471 * function in a tight loop.
472 *
473 * \param context the SDL_IOStream to query.
474 * \returns an SDL_IOStatus enum with the current state.
475 *
476 * \threadsafety This function should not be called at the same time that
477 * another thread is operating on the same SDL_IOStream.
478 *
479 * \since This function is available since SDL 3.1.3.
480 */
481extern SDL_DECLSPEC SDL_IOStatus SDLCALL SDL_GetIOStatus(SDL_IOStream *context);
482
483/**
484 * Use this function to get the size of the data stream in an SDL_IOStream.
485 *
486 * \param context the SDL_IOStream to get the size of the data stream from.
487 * \returns the size of the data stream in the SDL_IOStream on success or a
488 * negative error code on failure; call SDL_GetError() for more
489 * information.
490 *
491 * \since This function is available since SDL 3.1.3.
492 */
493extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetIOSize(SDL_IOStream *context);
494
495/**
496 * Seek within an SDL_IOStream data stream.
497 *
498 * This function seeks to byte `offset`, relative to `whence`.
499 *
500 * `whence` may be any of the following values:
501 *
502 * - `SDL_IO_SEEK_SET`: seek from the beginning of data
503 * - `SDL_IO_SEEK_CUR`: seek relative to current read point
504 * - `SDL_IO_SEEK_END`: seek relative to the end of data
505 *
506 * If this stream can not seek, it will return -1.
507 *
508 * \param context a pointer to an SDL_IOStream structure.
509 * \param offset an offset in bytes, relative to `whence` location; can be
510 * negative.
511 * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`,
512 * `SDL_IO_SEEK_END`.
513 * \returns the final offset in the data stream after the seek or -1 on
514 * failure; call SDL_GetError() for more information.
515 *
516 * \since This function is available since SDL 3.1.3.
517 *
518 * \sa SDL_TellIO
519 */
520extern SDL_DECLSPEC Sint64 SDLCALL SDL_SeekIO(SDL_IOStream *context, Sint64 offset, SDL_IOWhence whence);
521
522/**
523 * Determine the current read/write offset in an SDL_IOStream data stream.
524 *
525 * SDL_TellIO is actually a wrapper function that calls the SDL_IOStream's
526 * `seek` method, with an offset of 0 bytes from `SDL_IO_SEEK_CUR`, to
527 * simplify application development.
528 *
529 * \param context an SDL_IOStream data stream object from which to get the
530 * current offset.
531 * \returns the current offset in the stream, or -1 if the information can not
532 * be determined.
533 *
534 * \since This function is available since SDL 3.1.3.
535 *
536 * \sa SDL_SeekIO
537 */
538extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
539
540/**
541 * Read from a data source.
542 *
543 * This function reads up `size` bytes from the data source to the area
544 * pointed at by `ptr`. This function may read less bytes than requested.
545 *
546 * This function will return zero when the data stream is completely read, and
547 * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and
548 * the stream is not at EOF, SDL_GetIOStatus() will return a different error
549 * value and SDL_GetError() will offer a human-readable message.
550 *
551 * \param context a pointer to an SDL_IOStream structure.
552 * \param ptr a pointer to a buffer to read data into.
553 * \param size the number of bytes to read from the data source.
554 * \returns the number of bytes read, or 0 on end of file or other failure;
555 * call SDL_GetError() for more information.
556 *
557 * \since This function is available since SDL 3.1.3.
558 *
559 * \sa SDL_WriteIO
560 * \sa SDL_GetIOStatus
561 */
562extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size);
563
564/**
565 * Write to an SDL_IOStream data stream.
566 *
567 * This function writes exactly `size` bytes from the area pointed at by `ptr`
568 * to the stream. If this fails for any reason, it'll return less than `size`
569 * to demonstrate how far the write progressed. On success, it returns `size`.
570 *
571 * On error, this function still attempts to write as much as possible, so it
572 * might return a positive value less than the requested write size.
573 *
574 * The caller can use SDL_GetIOStatus() to determine if the problem is
575 * recoverable, such as a non-blocking write that can simply be retried later,
576 * or a fatal error.
577 *
578 * \param context a pointer to an SDL_IOStream structure.
579 * \param ptr a pointer to a buffer containing data to write.
580 * \param size the number of bytes to write.
581 * \returns the number of bytes written, which will be less than `size` on
582 * failure; call SDL_GetError() for more information.
583 *
584 * \since This function is available since SDL 3.1.3.
585 *
586 * \sa SDL_IOprintf
587 * \sa SDL_ReadIO
588 * \sa SDL_SeekIO
589 * \sa SDL_FlushIO
590 * \sa SDL_GetIOStatus
591 */
592extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size);
593
594/**
595 * Print to an SDL_IOStream data stream.
596 *
597 * This function does formatted printing to the stream.
598 *
599 * \param context a pointer to an SDL_IOStream structure.
600 * \param fmt a printf() style format string.
601 * \param ... additional parameters matching % tokens in the `fmt` string, if
602 * any.
603 * \returns the number of bytes written or 0 on failure; call SDL_GetError()
604 * for more information.
605 *
606 * \since This function is available since SDL 3.1.3.
607 *
608 * \sa SDL_IOvprintf
609 * \sa SDL_WriteIO
610 */
611extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2);
612
613/**
614 * Print to an SDL_IOStream data stream.
615 *
616 * This function does formatted printing to the stream.
617 *
618 * \param context a pointer to an SDL_IOStream structure.
619 * \param fmt a printf() style format string.
620 * \param ap a variable argument list.
621 * \returns the number of bytes written or 0 on failure; call SDL_GetError()
622 * for more information.
623 *
624 * \since This function is available since SDL 3.1.3.
625 *
626 * \sa SDL_IOprintf
627 * \sa SDL_WriteIO
628 */
629extern 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);
630
631/**
632 * Flush any buffered data in the stream.
633 *
634 * This function makes sure that any buffered data is written to the stream.
635 * Normally this isn't necessary but if the stream is a pipe or socket it
636 * guarantees that any pending data is sent.
637 *
638 * \param context SDL_IOStream structure to flush.
639 * \returns true on success or false on failure; call SDL_GetError() for more
640 * information.
641 *
642 * \since This function is available since SDL 3.1.3.
643 *
644 * \sa SDL_OpenIO
645 * \sa SDL_WriteIO
646 */
647extern SDL_DECLSPEC bool SDLCALL SDL_FlushIO(SDL_IOStream *context);
648
649/**
650 * Load all the data from an SDL data stream.
651 *
652 * The data is allocated with a zero byte at the end (null terminated) for
653 * convenience. This extra byte is not included in the value reported via
654 * `datasize`.
655 *
656 * The data should be freed with SDL_free().
657 *
658 * \param src the SDL_IOStream to read all available data from.
659 * \param datasize a pointer filled in with the number of bytes read, may be
660 * NULL.
661 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even
662 * in the case of an error.
663 * \returns the data or NULL on failure; call SDL_GetError() for more
664 * information.
665 *
666 * \since This function is available since SDL 3.1.3.
667 *
668 * \sa SDL_LoadFile
669 * \sa SDL_SaveFile_IO
670 */
671extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio);
672
673/**
674 * Load all the data from a file path.
675 *
676 * The data is allocated with a zero byte at the end (null terminated) for
677 * convenience. This extra byte is not included in the value reported via
678 * `datasize`.
679 *
680 * The data should be freed with SDL_free().
681 *
682 * \param file the path to read all available data from.
683 * \param datasize if not NULL, will store the number of bytes read.
684 * \returns the data or NULL on failure; call SDL_GetError() for more
685 * information.
686 *
687 * \since This function is available since SDL 3.1.3.
688 *
689 * \sa SDL_LoadFile_IO
690 * \sa SDL_SaveFile
691 */
692extern SDL_DECLSPEC void * SDLCALL SDL_LoadFile(const char *file, size_t *datasize);
693
694/**
695 * Save all the data into an SDL data stream.
696 *
697 * \param src the SDL_IOStream to write all data to.
698 * \param data the data to be written. If datasize is 0, may be NULL or a
699 * invalid pointer.
700 * \param datasize the number of bytes to be written.
701 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even
702 * in the case of an error.
703 * \returns true on success or false on failure; call SDL_GetError() for more
704 * information.
705 *
706 * \since This function is available since SDL 3.2.0.
707 *
708 * \sa SDL_SaveFile
709 * \sa SDL_LoadFile_IO
710 */
711extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio);
712
713/**
714 * Save all the data into a file path.
715 *
716 * \param file the path to read all available data from.
717 * \param data the data to be written. If datasize is 0, may be NULL or a
718 * invalid pointer.
719 * \param datasize the number of bytes to be written.
720 * \returns true on success or false on failure; call SDL_GetError() for more
721 * information.
722 *
723 * \since This function is available since SDL 3.2.0.
724 *
725 * \sa SDL_SaveFile_IO
726 * \sa SDL_LoadFile
727 */
728extern SDL_DECLSPEC bool SDLCALL SDL_SaveFile(const char *file, const void *data, size_t datasize);
729
730/**
731 * \name Read endian functions
732 *
733 * Read an item of the specified endianness and return in native format.
734 */
735/* @{ */
736
737/**
738 * Use this function to read a byte from an SDL_IOStream.
739 *
740 * This function will return false when the data stream is completely read,
741 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
742 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
743 * error value and SDL_GetError() will offer a human-readable message.
744 *
745 * \param src the SDL_IOStream to read from.
746 * \param value a pointer filled in with the data read.
747 * \returns true on success or false on failure or EOF; call SDL_GetError()
748 * for more information.
749 *
750 * \since This function is available since SDL 3.1.3.
751 */
752extern SDL_DECLSPEC bool SDLCALL SDL_ReadU8(SDL_IOStream *src, Uint8 *value);
753
754/**
755 * Use this function to read a signed byte from an SDL_IOStream.
756 *
757 * This function will return false when the data stream is completely read,
758 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
759 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
760 * error value and SDL_GetError() will offer a human-readable message.
761 *
762 * \param src the SDL_IOStream to read from.
763 * \param value a pointer filled in with the data read.
764 * \returns true on success or false on failure; call SDL_GetError() for more
765 * information.
766 *
767 * \since This function is available since SDL 3.1.3.
768 */
769extern SDL_DECLSPEC bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value);
770
771/**
772 * Use this function to read 16 bits of little-endian data from an
773 * SDL_IOStream and return in native format.
774 *
775 * SDL byteswaps the data only if necessary, so the data returned will be in
776 * the native byte order.
777 *
778 * This function will return false when the data stream is completely read,
779 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
780 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
781 * error value and SDL_GetError() will offer a human-readable message.
782 *
783 * \param src the stream from which to read data.
784 * \param value a pointer filled in with the data read.
785 * \returns true on successful write or false on failure; call SDL_GetError()
786 * for more information.
787 *
788 * \since This function is available since SDL 3.1.3.
789 */
790extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value);
791
792/**
793 * Use this function to read 16 bits of little-endian data from an
794 * SDL_IOStream and return in native format.
795 *
796 * SDL byteswaps the data only if necessary, so the data returned will be in
797 * the native byte order.
798 *
799 * This function will return false when the data stream is completely read,
800 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
801 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
802 * error value and SDL_GetError() will offer a human-readable message.
803 *
804 * \param src the stream from which to read data.
805 * \param value a pointer filled in with the data read.
806 * \returns true on successful write or false on failure; call SDL_GetError()
807 * for more information.
808 *
809 * \since This function is available since SDL 3.1.3.
810 */
811extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value);
812
813/**
814 * Use this function to read 16 bits of big-endian data from an SDL_IOStream
815 * and return in native format.
816 *
817 * SDL byteswaps the data only if necessary, so the data returned will be in
818 * the native byte order.
819 *
820 * This function will return false when the data stream is completely read,
821 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
822 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
823 * error value and SDL_GetError() will offer a human-readable message.
824 *
825 * \param src the stream from which to read data.
826 * \param value a pointer filled in with the data read.
827 * \returns true on successful write or false on failure; call SDL_GetError()
828 * for more information.
829 *
830 * \since This function is available since SDL 3.1.3.
831 */
832extern SDL_DECLSPEC bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value);
833
834/**
835 * Use this function to read 16 bits of big-endian data from an SDL_IOStream
836 * and return in native format.
837 *
838 * SDL byteswaps the data only if necessary, so the data returned will be in
839 * the native byte order.
840 *
841 * This function will return false when the data stream is completely read,
842 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
843 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
844 * error value and SDL_GetError() will offer a human-readable message.
845 *
846 * \param src the stream from which to read data.
847 * \param value a pointer filled in with the data read.
848 * \returns true on successful write or false on failure; call SDL_GetError()
849 * for more information.
850 *
851 * \since This function is available since SDL 3.1.3.
852 */
853extern SDL_DECLSPEC bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value);
854
855/**
856 * Use this function to read 32 bits of little-endian data from an
857 * SDL_IOStream and return in native format.
858 *
859 * SDL byteswaps the data only if necessary, so the data returned will be in
860 * the native byte order.
861 *
862 * This function will return false when the data stream is completely read,
863 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
864 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
865 * error value and SDL_GetError() will offer a human-readable message.
866 *
867 * \param src the stream from which to read data.
868 * \param value a pointer filled in with the data read.
869 * \returns true on successful write or false on failure; call SDL_GetError()
870 * for more information.
871 *
872 * \since This function is available since SDL 3.1.3.
873 */
874extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value);
875
876/**
877 * Use this function to read 32 bits of little-endian data from an
878 * SDL_IOStream and return in native format.
879 *
880 * SDL byteswaps the data only if necessary, so the data returned will be in
881 * the native byte order.
882 *
883 * This function will return false when the data stream is completely read,
884 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
885 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
886 * error value and SDL_GetError() will offer a human-readable message.
887 *
888 * \param src the stream from which to read data.
889 * \param value a pointer filled in with the data read.
890 * \returns true on successful write or false on failure; call SDL_GetError()
891 * for more information.
892 *
893 * \since This function is available since SDL 3.1.3.
894 */
895extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value);
896
897/**
898 * Use this function to read 32 bits of big-endian data from an SDL_IOStream
899 * and return in native format.
900 *
901 * SDL byteswaps the data only if necessary, so the data returned will be in
902 * the native byte order.
903 *
904 * This function will return false when the data stream is completely read,
905 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
906 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
907 * error value and SDL_GetError() will offer a human-readable message.
908 *
909 * \param src the stream from which to read data.
910 * \param value a pointer filled in with the data read.
911 * \returns true on successful write or false on failure; call SDL_GetError()
912 * for more information.
913 *
914 * \since This function is available since SDL 3.1.3.
915 */
916extern SDL_DECLSPEC bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value);
917
918/**
919 * Use this function to read 32 bits of big-endian data from an SDL_IOStream
920 * and return in native format.
921 *
922 * SDL byteswaps the data only if necessary, so the data returned will be in
923 * the native byte order.
924 *
925 * This function will return false when the data stream is completely read,
926 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
927 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
928 * error value and SDL_GetError() will offer a human-readable message.
929 *
930 * \param src the stream from which to read data.
931 * \param value a pointer filled in with the data read.
932 * \returns true on successful write or false on failure; call SDL_GetError()
933 * for more information.
934 *
935 * \since This function is available since SDL 3.1.3.
936 */
937extern SDL_DECLSPEC bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value);
938
939/**
940 * Use this function to read 64 bits of little-endian data from an
941 * SDL_IOStream and return in native format.
942 *
943 * SDL byteswaps the data only if necessary, so the data returned will be in
944 * the native byte order.
945 *
946 * This function will return false when the data stream is completely read,
947 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
948 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
949 * error value and SDL_GetError() will offer a human-readable message.
950 *
951 * \param src the stream from which to read data.
952 * \param value a pointer filled in with the data read.
953 * \returns true on successful write or false on failure; call SDL_GetError()
954 * for more information.
955 *
956 * \since This function is available since SDL 3.1.3.
957 */
958extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value);
959
960/**
961 * Use this function to read 64 bits of little-endian data from an
962 * SDL_IOStream and return in native format.
963 *
964 * SDL byteswaps the data only if necessary, so the data returned will be in
965 * the native byte order.
966 *
967 * This function will return false when the data stream is completely read,
968 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
969 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
970 * error value and SDL_GetError() will offer a human-readable message.
971 *
972 * \param src the stream from which to read data.
973 * \param value a pointer filled in with the data read.
974 * \returns true on successful write or false on failure; call SDL_GetError()
975 * for more information.
976 *
977 * \since This function is available since SDL 3.1.3.
978 */
979extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value);
980
981/**
982 * Use this function to read 64 bits of big-endian data from an SDL_IOStream
983 * and return in native format.
984 *
985 * SDL byteswaps the data only if necessary, so the data returned will be in
986 * the native byte order.
987 *
988 * This function will return false when the data stream is completely read,
989 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
990 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
991 * error value and SDL_GetError() will offer a human-readable message.
992 *
993 * \param src the stream from which to read data.
994 * \param value a pointer filled in with the data read.
995 * \returns true on successful write or false on failure; call SDL_GetError()
996 * for more information.
997 *
998 * \since This function is available since SDL 3.1.3.
999 */
1000extern SDL_DECLSPEC bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value);
1001
1002/**
1003 * Use this function to read 64 bits of big-endian data from an SDL_IOStream
1004 * and return in native format.
1005 *
1006 * SDL byteswaps the data only if necessary, so the data returned will be in
1007 * the native byte order.
1008 *
1009 * This function will return false when the data stream is completely read,
1010 * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned
1011 * and the stream is not at EOF, SDL_GetIOStatus() will return a different
1012 * error value and SDL_GetError() will offer a human-readable message.
1013 *
1014 * \param src the stream from which to read data.
1015 * \param value a pointer filled in with the data read.
1016 * \returns true on successful write or false on failure; call SDL_GetError()
1017 * for more information.
1018 *
1019 * \since This function is available since SDL 3.1.3.
1020 */
1021extern SDL_DECLSPEC bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value);
1022/* @} *//* Read endian functions */
1023
1024/**
1025 * \name Write endian functions
1026 *
1027 * Write an item of native format to the specified endianness.
1028 */
1029/* @{ */
1030
1031/**
1032 * Use this function to write a byte to an SDL_IOStream.
1033 *
1034 * \param dst the SDL_IOStream to write to.
1035 * \param value the byte value to write.
1036 * \returns true on successful write or false on failure; call SDL_GetError()
1037 * for more information.
1038 *
1039 * \since This function is available since SDL 3.1.3.
1040 */
1041extern SDL_DECLSPEC bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value);
1042
1043/**
1044 * Use this function to write a signed byte to an SDL_IOStream.
1045 *
1046 * \param dst the SDL_IOStream to write to.
1047 * \param value the byte value to write.
1048 * \returns true on successful write or false on failure; call SDL_GetError()
1049 * for more information.
1050 *
1051 * \since This function is available since SDL 3.1.3.
1052 */
1053extern SDL_DECLSPEC bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value);
1054
1055/**
1056 * Use this function to write 16 bits in native format to an SDL_IOStream as
1057 * little-endian data.
1058 *
1059 * SDL byteswaps the data only if necessary, so the application always
1060 * specifies native format, and the data written will be in little-endian
1061 * format.
1062 *
1063 * \param dst the stream to which data will be written.
1064 * \param value the data to be written, in native format.
1065 * \returns true on successful write or false on failure; call SDL_GetError()
1066 * for more information.
1067 *
1068 * \since This function is available since SDL 3.1.3.
1069 */
1070extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value);
1071
1072/**
1073 * Use this function to write 16 bits in native format to an SDL_IOStream as
1074 * little-endian data.
1075 *
1076 * SDL byteswaps the data only if necessary, so the application always
1077 * specifies native format, and the data written will be in little-endian
1078 * format.
1079 *
1080 * \param dst the stream to which data will be written.
1081 * \param value the data to be written, in native format.
1082 * \returns true on successful write or false on failure; call SDL_GetError()
1083 * for more information.
1084 *
1085 * \since This function is available since SDL 3.1.3.
1086 */
1087extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value);
1088
1089/**
1090 * Use this function to write 16 bits in native format to an SDL_IOStream as
1091 * big-endian data.
1092 *
1093 * SDL byteswaps the data only if necessary, so the application always
1094 * specifies native format, and the data written will be in big-endian format.
1095 *
1096 * \param dst the stream to which data will be written.
1097 * \param value the data to be written, in native format.
1098 * \returns true on successful write or false on failure; call SDL_GetError()
1099 * for more information.
1100 *
1101 * \since This function is available since SDL 3.1.3.
1102 */
1103extern SDL_DECLSPEC bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value);
1104
1105/**
1106 * Use this function to write 16 bits in native format to an SDL_IOStream as
1107 * big-endian data.
1108 *
1109 * SDL byteswaps the data only if necessary, so the application always
1110 * specifies native format, and the data written will be in big-endian format.
1111 *
1112 * \param dst the stream to which data will be written.
1113 * \param value the data to be written, in native format.
1114 * \returns true on successful write or false on failure; call SDL_GetError()
1115 * for more information.
1116 *
1117 * \since This function is available since SDL 3.1.3.
1118 */
1119extern SDL_DECLSPEC bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value);
1120
1121/**
1122 * Use this function to write 32 bits in native format to an SDL_IOStream as
1123 * little-endian data.
1124 *
1125 * SDL byteswaps the data only if necessary, so the application always
1126 * specifies native format, and the data written will be in little-endian
1127 * format.
1128 *
1129 * \param dst the stream to which data will be written.
1130 * \param value the data to be written, in native format.
1131 * \returns true on successful write or false on failure; call SDL_GetError()
1132 * for more information.
1133 *
1134 * \since This function is available since SDL 3.1.3.
1135 */
1136extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value);
1137
1138/**
1139 * Use this function to write 32 bits in native format to an SDL_IOStream as
1140 * little-endian data.
1141 *
1142 * SDL byteswaps the data only if necessary, so the application always
1143 * specifies native format, and the data written will be in little-endian
1144 * format.
1145 *
1146 * \param dst the stream to which data will be written.
1147 * \param value the data to be written, in native format.
1148 * \returns true on successful write or false on failure; call SDL_GetError()
1149 * for more information.
1150 *
1151 * \since This function is available since SDL 3.1.3.
1152 */
1153extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value);
1154
1155/**
1156 * Use this function to write 32 bits in native format to an SDL_IOStream as
1157 * big-endian data.
1158 *
1159 * SDL byteswaps the data only if necessary, so the application always
1160 * specifies native format, and the data written will be in big-endian format.
1161 *
1162 * \param dst the stream to which data will be written.
1163 * \param value the data to be written, in native format.
1164 * \returns true on successful write or false on failure; call SDL_GetError()
1165 * for more information.
1166 *
1167 * \since This function is available since SDL 3.1.3.
1168 */
1169extern SDL_DECLSPEC bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value);
1170
1171/**
1172 * Use this function to write 32 bits in native format to an SDL_IOStream as
1173 * big-endian data.
1174 *
1175 * SDL byteswaps the data only if necessary, so the application always
1176 * specifies native format, and the data written will be in big-endian format.
1177 *
1178 * \param dst the stream to which data will be written.
1179 * \param value the data to be written, in native format.
1180 * \returns true on successful write or false on failure; call SDL_GetError()
1181 * for more information.
1182 *
1183 * \since This function is available since SDL 3.1.3.
1184 */
1185extern SDL_DECLSPEC bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value);
1186
1187/**
1188 * Use this function to write 64 bits in native format to an SDL_IOStream as
1189 * little-endian data.
1190 *
1191 * SDL byteswaps the data only if necessary, so the application always
1192 * specifies native format, and the data written will be in little-endian
1193 * format.
1194 *
1195 * \param dst the stream to which data will be written.
1196 * \param value the data to be written, in native format.
1197 * \returns true on successful write or false on failure; call SDL_GetError()
1198 * for more information.
1199 *
1200 * \since This function is available since SDL 3.1.3.
1201 */
1202extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value);
1203
1204/**
1205 * Use this function to write 64 bits in native format to an SDL_IOStream as
1206 * little-endian data.
1207 *
1208 * SDL byteswaps the data only if necessary, so the application always
1209 * specifies native format, and the data written will be in little-endian
1210 * format.
1211 *
1212 * \param dst the stream to which data will be written.
1213 * \param value the data to be written, in native format.
1214 * \returns true on successful write or false on failure; call SDL_GetError()
1215 * for more information.
1216 *
1217 * \since This function is available since SDL 3.1.3.
1218 */
1219extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value);
1220
1221/**
1222 * Use this function to write 64 bits in native format to an SDL_IOStream as
1223 * big-endian data.
1224 *
1225 * SDL byteswaps the data only if necessary, so the application always
1226 * specifies native format, and the data written will be in big-endian format.
1227 *
1228 * \param dst the stream to which data will be written.
1229 * \param value the data to be written, in native format.
1230 * \returns true on successful write or false on failure; call SDL_GetError()
1231 * for more information.
1232 *
1233 * \since This function is available since SDL 3.1.3.
1234 */
1235extern SDL_DECLSPEC bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value);
1236
1237/**
1238 * Use this function to write 64 bits in native format to an SDL_IOStream as
1239 * big-endian data.
1240 *
1241 * SDL byteswaps the data only if necessary, so the application always
1242 * specifies native format, and the data written will be in big-endian format.
1243 *
1244 * \param dst the stream to which data will be written.
1245 * \param value the data to be written, in native format.
1246 * \returns true on successful write or false on failure; call SDL_GetError()
1247 * for more information.
1248 *
1249 * \since This function is available since SDL 3.1.3.
1250 */
1251extern SDL_DECLSPEC bool SDLCALL SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value);
1252
1253/* @} *//* Write endian functions */
1254
1255/* Ends C function definitions when using C++ */
1256#ifdef __cplusplus
1257}
1258#endif
1259#include <SDL3/SDL_close_code.h>
1260
1261#endif /* SDL_iostream_h_ */
bool SDL_WriteS64LE(SDL_IOStream *dst, Sint64 value)
SDL_IOStream * SDL_IOFromConstMem(const void *mem, size_t size)
SDL_IOStream * SDL_OpenIO(const SDL_IOStreamInterface *iface, void *userdata)
SDL_IOStatus
@ SDL_IO_STATUS_ERROR
@ SDL_IO_STATUS_EOF
@ SDL_IO_STATUS_NOT_READY
@ SDL_IO_STATUS_READY
@ SDL_IO_STATUS_WRITEONLY
@ SDL_IO_STATUS_READONLY
bool SDL_ReadU32LE(SDL_IOStream *src, Uint32 *value)
bool SDL_WriteS64BE(SDL_IOStream *dst, Sint64 value)
bool SDL_ReadS32LE(SDL_IOStream *src, Sint32 *value)
bool SDL_ReadU32BE(SDL_IOStream *src, Uint32 *value)
size_t SDL_WriteIO(SDL_IOStream *context, const void *ptr, size_t size)
bool SDL_WriteS32BE(SDL_IOStream *dst, Sint32 value)
bool SDL_WriteU16BE(SDL_IOStream *dst, Uint16 value)
bool SDL_ReadS64LE(SDL_IOStream *src, Sint64 *value)
bool SDL_ReadS8(SDL_IOStream *src, Sint8 *value)
bool SDL_ReadU16LE(SDL_IOStream *src, Uint16 *value)
Sint64 SDL_SeekIO(SDL_IOStream *context, Sint64 offset, SDL_IOWhence whence)
size_t SDL_IOvprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2)
SDL_IOStream * SDL_IOFromFile(const char *file, const char *mode)
bool SDL_WriteU16LE(SDL_IOStream *dst, Uint16 value)
Sint64 SDL_TellIO(SDL_IOStream *context)
bool SDL_WriteS32LE(SDL_IOStream *dst, Sint32 value)
bool SDL_WriteS8(SDL_IOStream *dst, Sint8 value)
bool SDL_WriteS16BE(SDL_IOStream *dst, Sint16 value)
size_t SDL_IOprintf(SDL_IOStream *context, SDL_PRINTF_FORMAT_STRING const char *fmt,...) SDL_PRINTF_VARARG_FUNC(2)
bool SDL_SaveFile(const char *file, const void *data, size_t datasize)
bool SDL_ReadS32BE(SDL_IOStream *src, Sint32 *value)
bool SDL_ReadU64BE(SDL_IOStream *src, Uint64 *value)
bool SDL_ReadU8(SDL_IOStream *src, Uint8 *value)
bool SDL_ReadS64BE(SDL_IOStream *src, Sint64 *value)
SDL_IOStream * SDL_IOFromDynamicMem(void)
void * SDL_LoadFile_IO(SDL_IOStream *src, size_t *datasize, bool closeio)
bool SDL_ReadS16LE(SDL_IOStream *src, Sint16 *value)
struct SDL_IOStream SDL_IOStream
bool SDL_ReadU16BE(SDL_IOStream *src, Uint16 *value)
bool SDL_WriteS16LE(SDL_IOStream *dst, Sint16 value)
bool SDL_WriteU64BE(SDL_IOStream *dst, Uint64 value)
bool SDL_WriteU32BE(SDL_IOStream *dst, Uint32 value)
Sint64 SDL_GetIOSize(SDL_IOStream *context)
bool SDL_SaveFile_IO(SDL_IOStream *src, const void *data, size_t datasize, bool closeio)
bool SDL_ReadS16BE(SDL_IOStream *src, Sint16 *value)
bool SDL_WriteU32LE(SDL_IOStream *dst, Uint32 value)
bool SDL_WriteU8(SDL_IOStream *dst, Uint8 value)
SDL_IOStatus SDL_GetIOStatus(SDL_IOStream *context)
SDL_IOStream * SDL_IOFromMem(void *mem, size_t size)
bool SDL_CloseIO(SDL_IOStream *context)
bool SDL_FlushIO(SDL_IOStream *context)
bool SDL_WriteU64LE(SDL_IOStream *dst, Uint64 value)
SDL_PropertiesID SDL_GetIOProperties(SDL_IOStream *context)
size_t SDL_ReadIO(SDL_IOStream *context, void *ptr, size_t size)
void * SDL_LoadFile(const char *file, size_t *datasize)
bool SDL_ReadU64LE(SDL_IOStream *src, Uint64 *value)
SDL_IOWhence
@ SDL_IO_SEEK_CUR
@ SDL_IO_SEEK_SET
@ SDL_IO_SEEK_END
Uint32 SDL_PropertiesID
uint8_t Uint8
Definition SDL_stdinc.h:337
int64_t Sint64
Definition SDL_stdinc.h:384
uint16_t Uint16
Definition SDL_stdinc.h:355
#define SDL_PRINTF_VARARG_FUNCV(fmtargnumber)
Definition SDL_stdinc.h:583
int8_t Sint8
Definition SDL_stdinc.h:328
int32_t Sint32
Definition SDL_stdinc.h:364
SDL_MALLOC size_t size
Definition SDL_stdinc.h:737
int16_t Sint16
Definition SDL_stdinc.h:346
#define SDL_PRINTF_FORMAT_STRING
Definition SDL_stdinc.h:571
#define SDL_PRINTF_VARARG_FUNC(fmtargnumber)
Definition SDL_stdinc.h:582
#define SDL_COMPILE_TIME_ASSERT(name, x)
Definition SDL_stdinc.h:112
#define bool
Definition SDL_stdinc.h:53
uint64_t Uint64
Definition SDL_stdinc.h:395
uint32_t Uint32
Definition SDL_stdinc.h:373
bool(* flush)(void *userdata, SDL_IOStatus *status)
Sint64(* size)(void *userdata)
size_t(* read)(void *userdata, void *ptr, size_t size, SDL_IOStatus *status)
Sint64(* seek)(void *userdata, Sint64 offset, SDL_IOWhence whence)
size_t(* write)(void *userdata, const void *ptr, size_t size, SDL_IOStatus *status)
bool(* close)(void *userdata)