eden-emu/SDL
14
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-15 17:28:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Updated documentation for functions that return temporary memory

Browse source
This commit is contained in:
Sam Lantinga 2024-07-19 10:54:27 -07:00
parent 68322ac851
commit 71a60d4c0e
24 changed files with 85 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

59
docs/README-strings.md
View file

@ -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.

16
include/SDL3/SDL_audio.h
View file

@ -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.

10
include/SDL3/SDL_camera.h
View file

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

4
include/SDL3/SDL_clipboard.h
View file

@ -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.

6
include/SDL3/SDL_error.h
View file

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

18
include/SDL3/SDL_events.h
View file

@ -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,9 +1425,9 @@ 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
* This function changes ownership of temporary memory allocated for events and functions 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.
*
* If the memory isn't temporary, or it was allocated on a different thread, or if it is associated with an event currently in the event queue, this will return NULL, and the application does not have ownership of the memory.
@ -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.

8
include/SDL3/SDL_filesystem.h
View file

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

30
include/SDL3/SDL_gamepad.h
View file

@ -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.

2
include/SDL3/SDL_guid.h
View file

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

6
include/SDL3/SDL_haptic.h
View file

@ -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,

2
include/SDL3/SDL_hints.h
View file

@ -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.

12
include/SDL3/SDL_joystick.h
View file

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

8
include/SDL3/SDL_keyboard.h
View file

@ -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.

2
include/SDL3/SDL_locale.h
View file

@ -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.

4
include/SDL3/SDL_mouse.h
View file

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

2
include/SDL3/SDL_pen.h
View file

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

2
include/SDL3/SDL_properties.h
View file

@ -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.

4
include/SDL3/SDL_render.h
View file

@ -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.

4
include/SDL3/SDL_sensor.h
View file

@ -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.

2
include/SDL3/SDL_storage.h
View file

@ -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.

8
include/SDL3/SDL_system.h
View file

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

2
include/SDL3/SDL_thread.h
View file

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

4
include/SDL3/SDL_touch.h
View file

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

16
include/SDL3/SDL_video.h
View file

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