[PATCH v3 2/4] Document malloc alignment

[Florian Weimer]

* Paul Eggert:

> * manual/memory.texi (Malloc Examples, Changing Block Size)
> (Allocating Cleared Space):
> Document the alignment of the returned value.
> ---
>  manual/memory.texi | 31 +++++++++++++++++++++++++++----
>  1 file changed, 27 insertions(+), 4 deletions(-)
>
> diff --git a/manual/memory.texi b/manual/memory.texi
> index f85e8ef26d..614cdc4e46 100644
> --- a/manual/memory.texi
> +++ b/manual/memory.texi
> @@ -652,10 +652,11 @@ savestring (const char *ptr, size_t len)
>  @end group
>  @end smallexample
>  
> -The block that @code{malloc} gives you is guaranteed to be aligned so
> -that it can hold any type of data.  On @gnusystems{}, the address is
> -always a multiple of eight on 32-bit systems, and a multiple of 16 on
> -64-bit systems.  Only rarely is any higher boundary (such as a page
> +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.
> +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}).

While at it, I would drop the “Only rarely” qualification because vector
code tends to require larger alignments.

>  
> @@ -677,6 +678,18 @@ returns a non-null pointer to a newly allocated size-zero block;
>  other implementations may return @code{NULL} instead.
>  POSIX and the ISO C standard allow both behaviors.
>  
> +@item
> +In @theglibc{}, a non-null pointer returned by @code{malloc (@var{size})}
> +is a multiple of @code{alignof (max_align_t)} when converted to an integer.
> +Other implementations may align the result only to what is needed for
> +fundamentally-aligned objects of size at most @code{max (@var{size}, 1)}.
> +For example, if @code{alignof (max_align_t)} is 16 but smaller
> +fundamentally-aligned objects all have alignment of at most 4,
> +other implementations of @code{malloc (15)} might return
> +a pointer that is a multiple of 4 but not of 16 or even of 8.
> +Portable code should therefore use a function like @code{aligned_alloc}
> +if it needs @code{alignof (max_align_t)} alignment even for small allocations.
> +
>  @item
>  In @theglibc{}, a failed @code{malloc} call sets @code{errno},
>  but ISO C does not require this and non-POSIX implementations
> @@ -866,6 +879,10 @@ Otherwise, if @var{newsize} is zero
>  Otherwise, if @code{realloc} cannot reallocate the requested size
>  it returns @code{NULL} and sets @code{errno}; the original block
>  is left undisturbed.
> +
> +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.
>  @end deftypefun

Maybe add something like this to the last paragraph?

  If the block was allocated with @code{aligned_alloc}, its alignment is
  not preserved.

I couldn't find a mention of this oddity anywhere.

There's also the matter that after using a block in realloc, you need to
call free_sized instead of free_aligned_sized, but addressing that
perhaps does not fit well with the changes in this series.

Thanks,
Florian