[PATCH 1/3] Document max_align_t

[Florian Weimer]

* Paul Eggert:

> +@deftp {Data Type} max_align_t
> +@standards{ISO, stddef.h}
> +@cindex fundamental alignment
> +This is an object type with the greatest @dfn{fundamental alignment},
> +i.e., the greatest alignment of all integer, floating, enumerated,
> +pointer, and standard library types such as @code{mbstate_t}, along
> +with all array, structure, and union types that are composed only of
> +these types and that lack stricter alignment specifiers.
> +Code can use @code{alignof (max_align_t)} when calculating space
> +needed for arbitrary collections of objects, so long as the objects'
> +types are fundamental and lack stricter alignment specifiers.
> +@end deftp

I think this is not entirely accurate because for ABI compatibility
reasons, we do not increase max_align_t when we add new types.

We could say that it's 8 on most 32-bit architectures, and 16 on 64-bit
architectures.  However, there are several 32-bit architectures that
require 16-byte alignment alignment from malloc to support certain
pre-defined types (which are not widely used in glibc).  But using
max_align_t the way you intended is probably the best programmers can do
in practice.

>  @strong{Compatibility Note:} Implementations of C before the advent of
>  @w{ISO C} generally used @code{unsigned int} for representing object sizes
>  and @code{int} for pointer subtraction results.  They did not
> -necessarily define either @code{size_t} or @code{ptrdiff_t}.  Unix
> +necessarily have @code{<stddef.h>} or define the types @code{size_t},
> +@code{ptrdiff_t}, or @code{max_align_t}.  Unix
>  systems did define @code{size_t}, in @file{sys/types.h}, but the
>  definition was usually a signed type.

Maybe drop the reference to signed size_t here?  I don't think we wan't
people to write code deals with this situation anymore.

Thanks,
Florian