diff --git a/docs/README-strings.md b/docs/README-strings.md deleted file mode 100644 index 58d94f9270af40..00000000000000 --- a/docs/README-strings.md +++ /dev/null @@ -1,59 +0,0 @@ -# String policies in SDL3. - -## Encoding. - -Unless otherwise specified, all strings in SDL, across all platforms, are -UTF-8 encoded and can represent the full range of [Unicode](https://unicode.org). - - -## The SDL Get String Rule. - -Did you see 'SDL_GetStringRule' in the wiki or headers? Here are the details -that aren't worth copying across dozens of functions' documentation. - -tl;dr: If an SDL function returns a `const char *` string, do not modify or -free it, and if you need to save it, make a copy right away. - -In several cases, SDL wants to return a string to the app, and the question -in any library that does this is: _who owns this thing?_ - -The answer in almost all cases, is that SDL does, but not for long. - -The pointer is only guaranteed to be valid until the next time the event -queue is updated, or SDL_Quit is called. - -The reason for this is memory safety. - -There are several strings that SDL provides that could be freed at -any moment. For example, an app calls SDL_GetAudioDeviceName(), which returns -a string that is part of the internal audio device structure. But, while this -function is returning, the user yanks the USB audio device out of the -computer, and SDL decides to deallocate the structure...and the string! -Now the app is holding a pointer that didn't live long enough to be useful, -and could crash if accessed. - -To avoid this, instead of calling SDL_free on a string as soon as it's done -with it, SDL adds the pointer to a list. This list is freed at specific -points: when the event queue is run (for ongoing cleanup) and when SDL_Quit -is called (to catch things that are just hanging around). This allows the -app to use a string without worrying about it becoming bogus in the middle -of a printf() call. If the app needs it for longer, it should copy it. - -When does "the event queue run"? There are several points: - -- If the app calls SDL_PumpEvents() _from any thread_. -- SDL_PumpEvents is also called by several other APIs internally: - SDL_PollEvent(), SDL_PeepEvents(), SDL_WaitEvent(), - SDL_WaitEventTimeout(), and maybe others. -- If you are using [the main callbacks](main-functions#main-callbacks-in-sdl3), - the event queue can run immediately after any of the callback functions - return. - -Note that these are just guaranteed minimum lifespans; any given string -might live much longer--some might even be static memory that is _never_ -deallocated--but this rule promises that the app has a safe window. - -Note that none of this applies if the return value is `char *` instead of -`const char *`. Please see the specific function's documentation for how -to handle those pointers. - diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index 72563c2a9a9616..c7966376602f94 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -400,7 +400,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * "coreaudio" or "wasapi". These never have Unicode characters, and are not * meant to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param index the index of the audio driver; the value ranges from 0 to * SDL_GetNumAudioDrivers() - 1. @@ -423,7 +423,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); * "coreaudio" or "wasapi". These never have Unicode characters, and are not * meant to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the name of the current audio driver or NULL if no driver has been * initialized. @@ -448,7 +448,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void); * If this function returns NULL, to signify an error, `*count` will be set to * zero. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of devices returned, may be NULL. * \returns a 0 terminated array of device instance IDs or NULL on error; call SDL_GetError() for more @@ -477,7 +477,7 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevice * If this function returns NULL, to signify an error, `*count` will be set to * zero. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of devices returned, may be NULL. * \returns a 0 terminated array of device instance IDs, or NULL on failure; call SDL_GetError() for more @@ -495,7 +495,7 @@ extern SDL_DECLSPEC const SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevic /** * Get the human-readable name of a specific audio device. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param devid the instance ID of the device to query. * \returns the name of the audio device, or NULL on failure; call @@ -555,7 +555,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid * Audio devices usually have no remapping applied. This is represented by * returning NULL, and does not signify an error. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param devid the instance ID of the device to query. * \param count On output, set to number of channels in the map. Can be NULL. @@ -1105,7 +1105,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, * Audio streams default to no remapping applied. This is represented by * returning NULL, and does not signify an error. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param stream the SDL_AudioStream to query. * \param count On output, set to number of channels in the map. Can be NULL. @@ -1130,7 +1130,7 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_Au * Audio streams default to no remapping applied. This is represented by * returning NULL, and does not signify an error. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param stream the SDL_AudioStream to query. * \param count On output, set to number of channels in the map. Can be NULL. diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h index 04db2eabff7409..0f3abbbc720e90 100644 --- a/include/SDL3/SDL_camera.h +++ b/include/SDL3/SDL_camera.h @@ -134,7 +134,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumCameraDrivers(void); * "coremedia" or "android". These never have Unicode characters, and are not * meant to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param index the index of the camera driver; the value ranges from 0 to * SDL_GetNumCameraDrivers() - 1. @@ -156,7 +156,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCameraDriver(int index); * "coremedia" or "android". These never have Unicode characters, and are not * meant to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the name of the current camera driver or NULL if no driver has * been initialized. @@ -170,7 +170,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentCameraDriver(void); /** * Get a list of currently connected camera devices. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of cameras returned, may be * NULL. @@ -207,7 +207,7 @@ extern SDL_DECLSPEC const SDL_CameraID * SDLCALL SDL_GetCameras(int *count); * _is_ a camera until the user has given you permission to check through a * scary warning popup. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param devid the camera device instance ID to query. * \param count a pointer filled in with the number of elements in the list, may be NULL. @@ -226,7 +226,7 @@ extern SDL_DECLSPEC const SDL_CameraSpec * const * SDLCALL SDL_GetCameraSupporte /** * Get the human-readable device name for a camera. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the camera device instance ID. * \returns a human-readable device name or NULL on failure; call diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h index 504f75ffcc5907..a1690f080a32f4 100644 --- a/include/SDL3/SDL_clipboard.h +++ b/include/SDL3/SDL_clipboard.h @@ -62,7 +62,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text); * This functions returns empty string if there was not enough memory left for * a copy of the clipboard's content. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the clipboard text on success or an empty string on failure; call * SDL_GetError() for more information. @@ -106,7 +106,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text); * This functions returns empty string if there was not enough memory left for * a copy of the primary selection's content. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the primary selection text on success or an empty string on * failure; call SDL_GetError() for more information. diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h index 141b8deee979ba..4c75829dde7350 100644 --- a/include/SDL3/SDL_error.h +++ b/include/SDL3/SDL_error.h @@ -96,10 +96,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_OutOfMemory(void); * Error strings are set per-thread, so an error set in a different thread * will not interfere with the current thread's operation. * - * The returned string does **NOT** follow the SDL_GetStringRule! The pointer - * is valid until the current thread's error string is changed, so the caller - * should make a copy if the string is to be used after calling into SDL - * again. + * The returned value is a thread-local string which will remain valid until the current thread's error string is changed. The caller + * should make a copy if the value is needed after the next SDL API call. * * \returns a message with information about the specific error that occurred, * or an empty string if there hasn't been an error message set since diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h index 2ee69991d5c0ac..91772e9a0e9edf 100644 --- a/include/SDL3/SDL_events.h +++ b/include/SDL3/SDL_events.h @@ -350,7 +350,7 @@ typedef struct SDL_KeyboardEvent * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * The text string follows the SDL_GetStringRule, and will be automatically freed later. + * The text string is temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \since This struct is available since SDL 3.0.0. */ @@ -368,7 +368,7 @@ typedef struct SDL_TextEditingEvent /** * Keyboard IME candidates event structure (event.edit_candidates.*) * - * The candidates follow the SDL_GetStringRule, and will be automatically freed later. + * The candidates are temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \since This struct is available since SDL 3.0.0. */ @@ -387,7 +387,7 @@ typedef struct SDL_TextEditingCandidatesEvent /** * Keyboard text input event structure (event.text.*) * - * The text string follows the SDL_GetStringRule, and will be automatically freed later. + * The text string is temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! @@ -784,7 +784,7 @@ typedef struct SDL_PenButtonEvent * An event used to drop text or request a file open by the system * (event.drop.*) * - * The source and data strings follow the SDL_GetStringRule, and will be automatically freed later. + * The source and data strings are temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \since This struct is available since SDL 3.0.0. */ @@ -1425,7 +1425,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents); extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size); /** - * Claim ownership of temporary memory allocated by SDL. + * Claim ownership of temporary memory. * * This function changes ownership of temporary memory allocated for events and APIs that * return temporary memory. If this function succeeds, the memory will no longer be automatically freed by SDL, it must be freed using SDL_free() by the application. @@ -1445,10 +1445,10 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AllocateTemporaryMemory(size_t size); extern SDL_DECLSPEC void * SDLCALL SDL_ClaimTemporaryMemory(const void *mem); /** - * Free temporary memory allocated by SDL. + * Free temporary memory. * - * This function frees temporary memory allocated for events and APIs that - * follow the SDL_GetStringRule. This memory is local to the thread that creates + * This function frees temporary memory allocated for events and functions that + * return temporary memory. This memory is local to the thread that creates * it and is automatically freed for the main thread when processing events. * For other threads you may call this function periodically to * free any temporary memory created by that thread. diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h index b3077b6046ed40..9c163ca544e433 100644 --- a/include/SDL3/SDL_filesystem.h +++ b/include/SDL3/SDL_filesystem.h @@ -68,7 +68,7 @@ extern "C" { * The returned path is guaranteed to end with a path separator ('\\' on * Windows, '/' on most other platforms). * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns an absolute path in UTF-8 encoding to the application data * directory. NULL will be returned on error or when the platform @@ -123,7 +123,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetBasePath(void); * The returned path is guaranteed to end with a path separator ('\\' on * Windows, '/' on most other platforms). * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param org the name of your organization. * \param app the name of your application. @@ -223,7 +223,7 @@ typedef enum SDL_Folder * The returned path is guaranteed to end with a path separator ('\\' on * Windows, '/' on most other platforms). * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * If NULL is returned, the error may be obtained with SDL_GetError(). * @@ -354,7 +354,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetPathInfo(const char *path, SDL_PathInfo * * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * - * The returned pointer follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param path the path of the directory to enumerate. * \param pattern the pattern that files in the directory must match. Can be diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h index 06b259465aa411..ac446d67c6abc6 100644 --- a/include/SDL3/SDL_gamepad.h +++ b/include/SDL3/SDL_gamepad.h @@ -389,7 +389,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void); /** * Get the current gamepad mappings. * - * The returned pointer follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of mappings returned, can * be NULL. @@ -403,7 +403,7 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou /** * Get the gamepad mapping string for a given GUID. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param guid a structure containing the GUID for which a mapping is desired. * \returns a mapping string or NULL on failure; call SDL_GetError() for more @@ -419,7 +419,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadMappingForGUID(SDL_GUID g /** * Get the current mapping of a gamepad. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * Details about mappings are discussed with SDL_AddGamepadMapping(). * @@ -468,7 +468,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void); /** * Get a list of currently connected gamepads. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of gamepads returned, may be NULL. * \returns a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for @@ -500,7 +500,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsGamepad(SDL_JoystickID instance_id); * * This can be called before any gamepads are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the joystick instance ID. * \returns the name of the selected gamepad. If no name can be found, this @@ -518,7 +518,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadNameForID(SDL_JoystickID * * This can be called before any gamepads are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the joystick instance ID. * \returns the path of the selected gamepad. If no path can be found, this @@ -651,7 +651,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetRealGamepadTypeForID(SDL_Joys * * This can be called before any gamepads are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the joystick instance ID. * \returns the mapping string. Returns NULL if no mapping is available. @@ -750,7 +750,7 @@ extern SDL_DECLSPEC SDL_JoystickID SDLCALL SDL_GetGamepadID(SDL_Gamepad *gamepad /** * Get the implementation-dependent name for an opened gamepad. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). @@ -766,7 +766,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadName(SDL_Gamepad *gamepad /** * Get the implementation-dependent path for an opened gamepad. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param gamepad a gamepad identifier previously returned by * SDL_OpenGamepad(). @@ -893,7 +893,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetGamepadFirmwareVersion(SDL_Gamepad *ga * * Returns the serial number of the gamepad, or NULL if it is not available. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param gamepad the gamepad object to query. * \returns the serial number, or NULL if unavailable. @@ -1053,7 +1053,7 @@ extern SDL_DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadTypeFromString(const c /** * Convert from an SDL_GamepadType enum to a string. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param type an enum value for a given SDL_GamepadType. * \returns a string for the given type, or NULL if an invalid type is @@ -1091,7 +1091,7 @@ extern SDL_DECLSPEC SDL_GamepadAxis SDLCALL SDL_GetGamepadAxisFromString(const c /** * Convert from an SDL_GamepadAxis enum to a string. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param axis an enum value for a given SDL_GamepadAxis. * \returns a string for the given axis, or NULL if an invalid axis is @@ -1166,7 +1166,7 @@ extern SDL_DECLSPEC SDL_GamepadButton SDLCALL SDL_GetGamepadButtonFromString(con /** * Convert from an SDL_GamepadButton enum to a string. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param button an enum value for a given SDL_GamepadButton. * \returns a string for the given button, or NULL if an invalid button is @@ -1454,7 +1454,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseGamepad(SDL_Gamepad *gamepad); * Return the sfSymbolsName for a given button on a gamepad on Apple * platforms. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param gamepad the gamepad to query. * \param button a button on the gamepad. @@ -1469,7 +1469,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetGamepadAppleSFSymbolsNameForButt /** * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param gamepad the gamepad to query. * \param axis an axis on the gamepad. diff --git a/include/SDL3/SDL_guid.h b/include/SDL3/SDL_guid.h index 3836a020b8bd4f..40a7465ec4d776 100644 --- a/include/SDL3/SDL_guid.h +++ b/include/SDL3/SDL_guid.h @@ -66,7 +66,7 @@ typedef struct SDL_GUID { /** * Get an ASCII string representation for a given SDL_GUID. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param guid the SDL_GUID you wish to convert to string. * \returns the string representation of the GUID or NULL on failure; call diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h index 058541cb96c403..e9d32bbae2c440 100644 --- a/include/SDL3/SDL_haptic.h +++ b/include/SDL3/SDL_haptic.h @@ -931,7 +931,7 @@ typedef Uint32 SDL_HapticID; /** * Get a list of currently connected haptic devices. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of haptic devices * returned, may be NULL. @@ -949,7 +949,7 @@ extern SDL_DECLSPEC const SDL_HapticID * SDLCALL SDL_GetHaptics(int *count); * * This can be called before any haptic devices are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the haptic device instance ID. * \returns the name of the selected haptic device. If no name can be found, @@ -1014,7 +1014,7 @@ extern SDL_DECLSPEC SDL_HapticID SDLCALL SDL_GetHapticID(SDL_Haptic *haptic); /** * Get the implementation dependent name of a haptic device. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick(). * \returns the name of the selected haptic device. If no name can be found, diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h index bd96fd6af3c5db..58cb8ebe65b399 100644 --- a/include/SDL3/SDL_hints.h +++ b/include/SDL3/SDL_hints.h @@ -3883,7 +3883,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_ResetHints(void); /** * Get the value of a hint. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param name the hint to query. * \returns the string value of a hint or NULL if the hint isn't set. diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h index f6f003a080e822..f999561c67f36f 100644 --- a/include/SDL3/SDL_joystick.h +++ b/include/SDL3/SDL_joystick.h @@ -201,7 +201,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void); /** * Get a list of currently connected joysticks. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of joysticks returned, may be NULL. * \returns a 0 terminated array of joystick instance IDs or NULL on failure; call SDL_GetError() for @@ -219,7 +219,7 @@ extern SDL_DECLSPEC const SDL_JoystickID * SDLCALL SDL_GetJoysticks(int *count); * * This can be called before any joysticks are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the joystick instance ID. * \returns the name of the selected joystick. If no name can be found, this @@ -237,7 +237,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickNameForID(SDL_JoystickID * * This can be called before any joysticks are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the joystick instance ID. * \returns the path of the selected joystick. If no path can be found, this @@ -658,7 +658,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetJoystickProperties(SDL_Joyst /** * Get the implementation dependent name of a joystick. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the name of the selected joystick. If no name can be found, this @@ -673,7 +673,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetJoystickName(SDL_Joystick *joyst /** * Get the implementation dependent path of a joystick. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the path of the selected joystick. If no path can be found, this @@ -792,7 +792,7 @@ extern SDL_DECLSPEC Uint16 SDLCALL SDL_GetJoystickFirmwareVersion(SDL_Joystick * * * Returns the serial number of the joystick, or NULL if it is not available. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param joystick the SDL_Joystick obtained from SDL_OpenJoystick(). * \returns the serial number of the selected joystick, or NULL if diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index f8c5067f1b4d2b..70f9fdfde65d75 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/include/SDL3/SDL_keyboard.h @@ -73,7 +73,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void); * power buttons, etc. You should wait for input from a device before you * consider it actively in use. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of keyboards returned, may be NULL. * \returns a 0 terminated array of keyboards instance IDs or NULL on failure; call SDL_GetError() for @@ -91,7 +91,7 @@ extern SDL_DECLSPEC const SDL_KeyboardID * SDLCALL SDL_GetKeyboards(int *count); * * This function returns "" if the keyboard doesn't have a name. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the keyboard instance ID. * \returns the name of the selected keyboard or NULL on failure; call @@ -281,7 +281,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetScancodeName(SDL_Scancode scancode, const /** * Get a human-readable name for a scancode. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * **Warning**: The returned name is by design not stable across platforms, * e.g. the name for `SDL_SCANCODE_LGUI` is "Left GUI" under Linux but "Left @@ -327,7 +327,7 @@ extern SDL_DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *nam * * If the key doesn't have a name, this function returns an empty string (""). * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param key the desired SDL_Keycode to query. * \returns a UTF-8 encoded string of the key name. diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h index 784841a3bfadc4..ec80f6dbb3149c 100644 --- a/include/SDL3/SDL_locale.h +++ b/include/SDL3/SDL_locale.h @@ -94,7 +94,7 @@ typedef struct SDL_Locale * if possible, and you can call this function again to get an updated copy of * preferred locales. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of locales returned, may * be NULL. diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h index abcedc30cbd57f..1a8bcce9d046e0 100644 --- a/include/SDL3/SDL_mouse.h +++ b/include/SDL3/SDL_mouse.h @@ -135,7 +135,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void); * You should wait for input from a device before you consider it actively in * use. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of mice returned, may be NULL. * \returns a 0 terminated array of mouse instance IDs or NULL on failure; call SDL_GetError() for more @@ -153,7 +153,7 @@ extern SDL_DECLSPEC const SDL_MouseID * SDLCALL SDL_GetMice(int *count); * * This function returns "" if the mouse doesn't have a name. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the mouse instance ID. * \returns the name of the selected mouse, or NULL on failure; call diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index b11f6960899ea6..899c3e33914632 100644 --- a/include/SDL3/SDL_pen.h +++ b/include/SDL3/SDL_pen.h @@ -224,7 +224,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id); /** * Retrieves a human-readable description for a SDL_PenID. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the pen to query. * \returns a string that contains the name of the pen, intended for human diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h index cd11eeedf4be6a..c466b7404344b3 100644 --- a/include/SDL3/SDL_properties.h +++ b/include/SDL3/SDL_properties.h @@ -378,7 +378,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props /** * Get a string property from a group of properties. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param props the properties to query. * \param name the name of the property to query. diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index bfff4534ebc817..b3dfc8a9933cda 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -154,7 +154,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); * "direct3d12" or "metal". These never have Unicode characters, and are not * meant to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param index the index of the rendering driver; the value ranges from 0 to * SDL_GetNumRenderDrivers() - 1. @@ -324,7 +324,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetRenderWindow(SDL_Renderer *rende /** * Get the name of a renderer. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param renderer the rendering context. * \returns the name of the selected renderer, or NULL on failure; call SDL_GetError() for more information. diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h index 2743f3734b7f84..9984566111de62 100644 --- a/include/SDL3/SDL_sensor.h +++ b/include/SDL3/SDL_sensor.h @@ -159,7 +159,7 @@ extern SDL_DECLSPEC const SDL_SensorID * SDLCALL SDL_GetSensors(int *count); * * This can be called before any sensors are opened. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param instance_id the sensor instance ID. * \returns the sensor name, or NULL if `instance_id` is not valid. @@ -228,7 +228,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor /** * Get the implementation dependent name of a sensor. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param sensor the SDL_Sensor object. * \returns the sensor name or NULL on failure; call SDL_GetError() for more information. diff --git a/include/SDL3/SDL_storage.h b/include/SDL3/SDL_storage.h index 0fa24a20fe03de..6f2308fc3ddb56 100644 --- a/include/SDL3/SDL_storage.h +++ b/include/SDL3/SDL_storage.h @@ -383,7 +383,7 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetStorageSpaceRemaining(SDL_Storage *sto * convenience, but if `count` is non-NULL, on return it will contain the * number of items in the array, not counting the NULL terminator. * - * The returned pointer follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param storage a storage container. * \param path the path of the directory to enumerate. diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index 01561551c3a4b5..cf88a029f90292 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -407,7 +407,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * * https://developer.android.com/reference/android/content/Context#getFilesDir() * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the path used for internal storage or NULL on failure; call * SDL_GetError() for more information. @@ -448,7 +448,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetAndroidExternalStorageState(void); * * https://developer.android.com/reference/android/content/Context#getExternalFilesDir() * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the path used for external storage for this application on success * or NULL on failure; call SDL_GetError() for more information. @@ -471,7 +471,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) * * https://developer.android.com/reference/android/content/Context#getCacheDir() * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the path used for caches for this application on success or NULL * on failure; call SDL_GetError() for more information. @@ -625,7 +625,7 @@ typedef enum SDL_WinRT_DeviceFamily * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param pathType the type of path to retrieve, one of SDL_WinRT_Path. * \returns a UTF-8 string (8-bit, multi-byte) containing the path, or NULL if diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h index 7bf7b1849a848d..7048cbb070a8c6 100644 --- a/include/SDL3/SDL_thread.h +++ b/include/SDL3/SDL_thread.h @@ -330,7 +330,7 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S /** * Get the thread name as it was specified in SDL_CreateThread(). * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param thread the thread to query. * \returns a pointer to a UTF-8 string that names the specified thread, or diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h index 808a69ea437b84..58e6cd0e56784c 100644 --- a/include/SDL3/SDL_touch.h +++ b/include/SDL3/SDL_touch.h @@ -83,7 +83,7 @@ typedef struct SDL_Finger * Therefore the returned list might be empty, although devices are available. * After using all devices at least once the number will be correct. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of devices returned, may * be NULL. @@ -97,7 +97,7 @@ extern SDL_DECLSPEC const SDL_TouchID * SDLCALL SDL_GetTouchDevices(int *count); /** * Get the touch device name as reported from the driver. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param touchID the touch device instance ID. * \returns touch device name, or NULL on failure; call SDL_GetError() for more diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index af7d52a9bab192..b1203528d1a426 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -349,7 +349,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * "x11" or "windows". These never have Unicode characters, and are not meant * to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. @@ -367,7 +367,7 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetVideoDriver(int index); * "x11" or "windows". These never have Unicode characters, and are not meant * to be proper names. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \returns the name of the current video driver or NULL if no driver has been * initialized. @@ -391,7 +391,7 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void); /** * Get a list of currently connected displays. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of displays returned, may * be NULL. @@ -446,7 +446,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetDisplayProperties(SDL_Displa /** * Get the name of a display in UTF-8 encoding. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param displayID the instance ID of the display to query. * \returns the name of a display or NULL on failure; call SDL_GetError() for @@ -555,7 +555,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ * - refresh rate -> highest to lowest * - pixel density -> lowest to highest * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param displayID the instance ID of the display to query. * \param count a pointer filled in with the number of display modes returned, may be NULL. @@ -767,7 +767,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode * SDLCALL SDL_GetWindowFullscreenMode( /** * Get the raw ICC profile data for the screen the window is currently on. * - * The returned data follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param window the window to query. * \param size the size of the ICC profile. @@ -793,7 +793,7 @@ extern SDL_DECLSPEC SDL_PixelFormat SDLCALL SDL_GetWindowPixelFormat(SDL_Window /** * Get a list of valid windows. * - * The returned array follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param count a pointer filled in with the number of windows returned, may * be NULL. @@ -1306,7 +1306,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowTitle(SDL_Window *window, const cha /** * Get the title of a window. * - * The returned string follows the SDL_GetStringRule, and will be automatically freed later. + * This returns temporary memory which will be automatically freed later, and can be claimed with SDL_ClaimTemporaryMemory(). * * \param window the window to query. * \returns the title of the window in UTF-8 format or "" if there is no