[PATCH 0/2] document improvements for max_align_t, intmax_t

[PATCH 0/2] document improvements for max_align_t, intmax_t

[Paul Eggert]

This follows up on my previous patchset to document max_align_t.
This patchset mentions the hazards of using intmax_t or max_align_t in
an external API, and documents that there can be integer types wider
than intmax_t.

Paul Eggert (2):
  doc: document max_align_t effect on ABI
  doc: document C23 changes to intmax_t

 manual/arith.texi | 20 ++++++++++++++++----
 manual/lang.texi  |  8 +++++++-
 2 files changed, 23 insertions(+), 5 deletions(-)

--
2.51.0

[PATCH 1/2] doc: document max_align_t effect on ABI

[Paul Eggert]

* 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(-)

diff --git a/manual/lang.texi b/manual/lang.texi
index 28e7de2b2c..5f6f74ebb9 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -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
-- 
2.51.0

Re: [PATCH 1/2] doc: document max_align_t effect on ABI

[DJ Delorie]

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>

[PATCH 2/2] doc: document C23 changes to intmax_t

[Paul Eggert]

* manual/arith.texi (Integers): Say that intmax_t/uintmax_t might
be narrower than some integer types.  Use wording of C23.
Also mention __int128, and that ABI changes if intmax_t changes.
---
 manual/arith.texi | 20 ++++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/manual/arith.texi b/manual/arith.texi
index df6d25e0ba..9f442e4bdd 100644
--- a/manual/arith.texi
+++ b/manual/arith.texi
@@ -96,16 +96,28 @@ one of these:
 @item uint_fast64_t
 @end itemize
 
-If you want an integer with the widest range possible on the platform on
-which it is being used, use one of the following.  If you use these,
-you should write code that takes into account the variable size and range
-of the integer.
+If you want an integer with a wide range, use one of these:
 
 @itemize @bullet
 @item intmax_t
 @item uintmax_t
 @end itemize
 
+@noindent
+The @code{intmax_t} type is wide enough to hold any signed integer value,
+with the possible exceptions of signed bit-precise integer types,
+and of @code{int@var{N}_t} types that are wider than @code{long long int}.
+Compilers may also support other integer types wider than
+@code{intmax_t}, such as GCC's @code{__int128}.
+The @code{uintmax_t} type is like @code{intmax_t},
+except for unsigned integers.
+
+Code that uses @code{intmax_t} or @code{uintmax_t} should take into
+account the variable size, range and alignment of the types.
+For example, it is unwise for a public interface to rely on @code{intmax_t},
+as the interface's ABI can change if a different compiler
+defines @code{intmax_t} differently.
+
 @Theglibc{} also provides macros that tell you the maximum and
 minimum possible values for each integer data type.  The macro names
 follow these examples: @code{INT32_MAX}, @code{UINT8_MAX},
-- 
2.51.0

Re: [PATCH 2/2] doc: document C23 changes to intmax_t

[DJ Delorie]

Paul Eggert <eggert@cs.ucla.edu> writes:
> -If you want an integer with the widest range possible on the platform on
> -which it is being used, use one of the following.  If you use these,
> -you should write code that takes into account the variable size and range
> -of the integer.
> +If you want an integer with a wide range, use one of these:

Perhaps "with the widest range of any standard type," ?

>  @itemize @bullet
>  @item intmax_t
>  @item uintmax_t
>  @end itemize
>  
> +@noindent
> +The @code{intmax_t} type is wide enough to hold any signed integer value,
> +with the possible exceptions of signed bit-precise integer types,
> +and of @code{int@var{N}_t} types that are wider than @code{long long int}.
> +Compilers may also support other integer types wider than
> +@code{intmax_t}, such as GCC's @code{__int128}.
> +The @code{uintmax_t} type is like @code{intmax_t},
> +except for unsigned integers.
> +
> +Code that uses @code{intmax_t} or @code{uintmax_t} should take into
> +account the variable size, range and alignment of the types.
> +For example, it is unwise for a public interface to rely on @code{intmax_t},
> +as the interface's ABI can change if a different compiler
> +defines @code{intmax_t} differently.
> +
>  @Theglibc{} also provides macros that tell you the maximum and
>  minimum possible values for each integer data type.  The macro names
>  follow these examples: @code{INT32_MAX}, @code{UINT8_MAX},

Otherwise LGTM
Reviewed-by: DJ Delorie <dj@redhat.com>