[1/2] doc: document max_align_t effect on ABI
Checks
| Context |
Check |
Description |
| redhat-pt-bot/TryBot-apply_patch |
success
|
Patch applied to master at the time it was sent
|
| linaro-tcwg-bot/tcwg_glibc_build--master-aarch64 |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_glibc_check--master-aarch64 |
success
|
Test passed
|
| linaro-tcwg-bot/tcwg_glibc_build--master-arm |
success
|
Build passed
|
| linaro-tcwg-bot/tcwg_glibc_check--master-arm |
success
|
Test passed
|
Commit Message
* manual/lang.texi (Important Data Types): Say that ABI changes if
max_align_t changes.
---
manual/lang.texi | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
Comments
Paul Eggert <eggert@cs.ucla.edu> writes:
> -@end deftp
Elsewhere in the manual, it seems that the rule is that text defining
the type goes inside the @deftp, and text describing how to use it goes
outside it. Since @deftp text is indented (in pdf at least), we should
be consistent here. See the first page or so of the Input/Output on
Streams chapter. However, given the rest of the text in this section, I
don't think it matters which way you choose.
> +Code that uses @code{max_align_t} should take into account the
> +variable alignment of the type.
This is a slightly confusing wording, but only because we don't think of
types being aligned, just the objects of that type being aligned, and
"variable" could mean something different than "changing". A type
imposes an alignment, it doesn't "have" one because a type doesn't
occupy memory.
Perhaps "should not rely on its alignment being constant for any given
platform." ?
> +For example, it is unwise for a public interface to rely on @code{max_align_t},
> +as the interface's ABI can change if a different compiler defines
> +@code{max_align_t} differently.
> +
This part is fine.
I don't feel strongly enough about any of the above to hold this back
as-is though, if you don't feel like changing it.
Reviewed-by: DJ Delorie <dj@redhat.com>
@@ -592,15 +592,21 @@ i.e., the greatest alignment needed by standard types.
Code can use @code{alignof (max_align_t)} when calculating space
needed for arbitrary collections of objects, so long as the objects'
types have a fundamental alignment and lack stricter alignment specifiers.
-@end deftp
In @theglibc{}, the value of @code{alignof (max_align_t)} is 16 on
most architectures. However, it is 8 on 32-bit architectures that do
not require 16-byte alignment from @code{malloc} to support predefined
types.
+Code that uses @code{max_align_t} should take into account the
+variable alignment of the type.
+For example, it is unwise for a public interface to rely on @code{max_align_t},
+as the interface's ABI can change if a different compiler defines
+@code{max_align_t} differently.
+
@strong{Compatibility Note:} The C11 standard introduced @code{max_align_t};
older compilers may lack the type.
+@end deftp
@node Data Type Measurements
@section Data Type Measurements