From 61e7878ac024cca02b2aa76c9b0af809bb1ab44e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carl=20=C3=85stholm?= <[EMAIL REDACTED]>
Date: Tue, 25 Mar 2025 02:28:25 +0100
Subject: [PATCH] Document SDL_malloc alignment guarantees
(cherry picked from commit 7ec13a2ead3c139b5b2bf0fd154a7d65133231bd)
---
include/SDL3/SDL_stdinc.h | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 9903a0b0f7a86..b2728da2f4c47 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -1299,8 +1299,11 @@ extern "C" {
*
* If `size` is 0, it will be set to 1.
*
- * If you want to allocate memory aligned to a specific alignment, consider
- * using SDL_aligned_alloc().
+ * If the allocation is successful, the returned pointer is guaranteed to be
+ * aligned to either the *fundamental alignment* (`alignof(max_align_t)` in
+ * C11 and later) or `2 * sizeof(void *)`, whichever is smaller. Use
+ * SDL_aligned_alloc() if you need to allocate memory aligned to an alignment
+ * greater than this guarantee.
*
* \param size the size to allocate.
* \returns a pointer to the allocated memory, or NULL if allocation failed.
@@ -1323,6 +1326,10 @@ extern SDL_DECLSPEC SDL_MALLOC void * SDLCALL SDL_malloc(size_t size);
*
* If either of `nmemb` or `size` is 0, they will both be set to 1.
*
+ * If the allocation is successful, the returned pointer is guaranteed to be
+ * aligned to either the *fundamental alignment* (`alignof(max_align_t)` in
+ * C11 and later) or `2 * sizeof(void *)`, whichever is smaller.
+ *
* \param nmemb the number of elements in the array.
* \param size the size of each element of the array.
* \returns a pointer to the allocated array, or NULL if allocation failed.
@@ -1357,6 +1364,11 @@ extern SDL_DECLSPEC SDL_MALLOC SDL_ALLOC_SIZE2(1, 2) void * SDLCALL SDL_calloc(s
* - If it returns NULL (indicating failure), then `mem` will remain valid and
* must still be freed with SDL_free().
*
+ * If the allocation is successfully resized, the returned pointer is
+ * guaranteed to be aligned to either the *fundamental alignment*
+ * (`alignof(max_align_t)` in C11 and later) or `2 * sizeof(void *)`,
+ * whichever is smaller.
+ *
* \param mem a pointer to allocated memory to reallocate, or NULL.
* \param size the new size of the memory.
* \returns a pointer to the newly allocated memory, or NULL if allocation