[PATCH 2/3] Document malloc alignment

[Paul Eggert]

On 2026-02-06 01:38, Florian Weimer wrote:
> * Paul Eggert:
>> +In @theglibc{}, the block that @code{malloc} gives you is guaranteed
>> +to be aligned so that its address is a multiple of
>> +@code{alignof (max_align_t)}, so that it can hold object types
>> +with any fundamental alignment and without stricter alignment specifiers.
>> +On @gnusystems{}, this means the address is a multiple of 16 or of 8,
>> +depending on the system.
>> +Only rarely is any higher boundary (such as a page
>>   boundary) necessary; for those cases, use @code{aligned_alloc} or
>>   @code{posix_memalign} (@pxref{Aligned Memory Blocks}).
> 
> I think this should cross-reference Replacing malloc, and mention that
> malloc replacements sometimes do not follow this rule.

Yes, I could put this next to the looser alignments C23 guarantees.

> 
>> +@item
>> +In implementations other than @theglibc{}, a non-null pointer returned
>> +by @code{malloc (@var{size})} is guaranteed to be aligned only for
>> +fundamentally-aligned objects of size at most @code{max (@var{size}, 1)}.
> 
> I don't understand this.
> 
> I think the rule is that sizes of the fundamental alignment and larger
> have fundamental alignment, but sizes less than the fundamental
> alignment have alignment that is the largest power of two less than the
> size.  Maybe that's equivalent to your formulation in many cases?

No, as the formulation you give mixes up sizes and alignments, and there 
is no single fundamental alignment. For example, suppose alignof 
(max_align_t) == 8 but this alignment is needed only by a 16-byte long 
double, and all other fundamental alignments are 4 or less. Then C23 
says that malloc (8) need not return a multiple of 8.

The wording in C23 section 7.24.3 paragraph 1 is, "The pointer returned 
if the allocation succeeds is suitably aligned so that it may be 
assigned to a pointer to any type of object with a fundamental alignment 
requirement and size less than or equal to the size requested." What I 
wrote is a condensation of that (along with the fact that size-0 
requests are treated as size 1 when they return non-null).


> I would like us to avoid to get into a debate here what constitutes a
> fundamentally aligned object.

I don't see the hazard here. C23 defines what it means for an object to 
be fundamentally aligned; is there any reason to debate it?

> 
>> +Any non-null pointer returned by @code{realloc} satisfies the same
>> +alignment restrictions as a similar pointer returned by @code{malloc}
>> +with the same size.
> 
> Please mention here that any special alignment created by memalign et
> al. will be lost after realloc.

Good point, thanks.


>> +In @theglibc{}, the vector is aligned the same way that @code{malloc}
>> +aligns its returned values.  In other implementations, it is merely
>> +aligned suitably for any array of fundamentally-aligned elements each
>> +with size at most @code{max (@var{size}, 1)}.
> 
> Is this a C standard thing?  Does the same rule apply to calloc, which
> has a similar element count/element size split after all?

The "In other implementations" sentence is my description of reality as 
best I know it. The C standard is silent on the issue, unfortunately. I 
doubt whether any implementation would violate the description I gave. 
And yes, the same rule applies to calloc as to reallocarray.