[PATCH v3 0/4] malloc doc fixes for alignment

[PATCH v3 0/4] malloc doc fixes for alignment

[Paul Eggert]

This patch series affects only the manual.  Tt adds documentation for
max_align_t and documents how malloc and friends align their results.
Also, it says that systems where malloc (0) returns NULL are now rare,
and reorganizes for clarity to separate examples from portability notes.

v3 incorporates comments from DJ Delorie in:
https://sourceware.org/pipermail/libc-alpha/2026-February/175060.html
https://sourceware.org/pipermail/libc-alpha/2026-February/175061.html
https://sourceware.org/pipermail/libc-alpha/2026-February/175062.html

v2 incorporated comments from Floriam Weimer and Wilco Dijkstra in:
https://sourceware.org/pipermail/libc-alpha/2026-February/174910.html
https://sourceware.org/pipermail/libc-alpha/2026-February/174994.html
https://sourceware.org/pipermail/libc-alpha/2026-February/174911.html
https://sourceware.org/pipermail/libc-alpha/2026-February/174916.html
As a result there is now a new, 4th patch that adds documentation on
possible future changes.

Paul Eggert (4):
  Document max_align_t
  Document malloc alignment
  Say malloc (0) != NULL is now common; resection
  malloc: alignment might change in future versions

 NEWS               |   7 ++-
 manual/lang.texi   |  28 +++++++---
 manual/memory.texi | 131 ++++++++++++++++++++++++++++++++++++---------
 3 files changed, 131 insertions(+), 35 deletions(-)

--
2.51.0

[PATCH v3 1/4] Document max_align_t

[Paul Eggert]

* manual/lang.texi (Important Data Types): Mention max_align_t.
---
 manual/lang.texi | 28 ++++++++++++++++++++--------
 1 file changed, 20 insertions(+), 8 deletions(-)

diff --git a/manual/lang.texi b/manual/lang.texi
index cd90ff60d2..28e7de2b2c 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -16,7 +16,7 @@ features has been written, we are publishing it here.
 * Variadic Functions::          Defining functions with varying numbers
                                  of args.
 * Null Pointer Constant::       The macro @code{NULL}.
-* Important Data Types::        Data types for object sizes.
+* Important Data Types::        Types for sizes and alignments of objects.
 * Data Type Measurements::      Parameters of data type representations.
 @end menu
 
@@ -555,7 +555,8 @@ recommend instead adding a prototype for the function you are calling.
 The result of subtracting two pointers in C is always an integer, but the
 precise data type varies from C compiler to C compiler.  Likewise, the
 data type of the result of @code{sizeof} also varies between compilers.
-ISO C defines standard aliases for these two types, so you can refer to
+Also, it helps to have a data type with the greatest fundamental alignment.
+ISO C defines standard aliases for these types, so you can refer to
 them in a portable fashion.  They are defined in the header file
 @file{stddef.h}.
 @pindex stddef.h
@@ -583,12 +584,23 @@ will be @w{@code{unsigned int}} or @w{@code{unsigned long int}}.
 arguments or variables that hold the size of an object.
 @end deftp
 
-@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
-systems did define @code{size_t}, in @file{sys/types.h}, but the
-definition was usually a signed type.
+@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 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.
+
+@strong{Compatibility Note:} The C11 standard introduced @code{max_align_t};
+older compilers may lack the type.
 
 @node Data Type Measurements
 @section Data Type Measurements
-- 
2.51.0

Re: [PATCH v3 1/4] Document max_align_t

[Florian Weimer]

* Paul Eggert:

> * manual/lang.texi (Important Data Types): Mention max_align_t.
> ---
>  manual/lang.texi | 28 ++++++++++++++++++++--------
>  1 file changed, 20 insertions(+), 8 deletions(-)
>
> diff --git a/manual/lang.texi b/manual/lang.texi
> index cd90ff60d2..28e7de2b2c 100644
> --- a/manual/lang.texi
> +++ b/manual/lang.texi
> @@ -16,7 +16,7 @@ features has been written, we are publishing it here.
>  * Variadic Functions::          Defining functions with varying numbers
>                                   of args.
>  * Null Pointer Constant::       The macro @code{NULL}.
> -* Important Data Types::        Data types for object sizes.
> +* Important Data Types::        Types for sizes and alignments of objects.
>  * Data Type Measurements::      Parameters of data type representations.
>  @end menu
>  
> @@ -555,7 +555,8 @@ recommend instead adding a prototype for the function you are calling.
>  The result of subtracting two pointers in C is always an integer, but the
>  precise data type varies from C compiler to C compiler.  Likewise, the
>  data type of the result of @code{sizeof} also varies between compilers.
> -ISO C defines standard aliases for these two types, so you can refer to
> +Also, it helps to have a data type with the greatest fundamental alignment.
> +ISO C defines standard aliases for these types, so you can refer to
>  them in a portable fashion.  They are defined in the header file
>  @file{stddef.h}.
>  @pindex stddef.h
> @@ -583,12 +584,23 @@ will be @w{@code{unsigned int}} or @w{@code{unsigned long int}}.
>  arguments or variables that hold the size of an object.
>  @end deftp
>  
> -@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
> -systems did define @code{size_t}, in @file{sys/types.h}, but the
> -definition was usually a signed type.
> +@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 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.
> +
> +@strong{Compatibility Note:} The C11 standard introduced @code{max_align_t};
> +older compilers may lack the type.

This version looks good to me.

Reviewed-by: Florian Weimer <fweimer@redhat.com>

Thanks,
Florian

[PATCH v3 2/4] Document malloc alignment

[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}).
 
@@ -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
 
 @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
@@ -980,6 +997,12 @@ is declared in @file{stdlib.h}.
 This function allocates a block long enough to contain a vector of
 @var{count} elements, each of size @var{eltsize}.  Its contents are
 cleared to zero before @code{calloc} returns.
+
+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)}.
+
 @end deftypefun
 
 You could define @code{calloc} as follows:
-- 
2.51.0

Re: [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

Re: [PATCH v3 2/4] Document malloc alignment

[Florian Weimer]

* Florian Weimer:

> 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.

Sorry, missed that it's part of the third patch.

Florian

Re: [PATCH v3 2/4] Document malloc alignment

[Florian Weimer]

* Florian Weimer:

> * Florian Weimer:
>
>> 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.
>
> Sorry, missed that it's part of the third patch.

And considering this:

Reviewed-by: Florian Weimer <fweimer@redhat.com>

Thanks,
Florian

[PATCH v3 3/4] Say malloc (0) != NULL is now common; resection

[Paul Eggert]

* manual/memory.texi (Portable Allocation):
New section, split off from Malloc Examples.
Say that almost every system follows glibc's example
in having successful malloc (0) return non-null;
AIX is the only exception nowadays.
Document fundamental alignment portability.
Have examples match the new text, and use NULL rather than 0.
---
 manual/memory.texi | 130 +++++++++++++++++++++++++++++++--------------
 1 file changed, 91 insertions(+), 39 deletions(-)

diff --git a/manual/memory.texi b/manual/memory.texi
index 614cdc4e46..935df79e9c 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -318,6 +318,7 @@ any time (or never).
 @menu
 * Basic Allocation::            Simple use of @code{malloc}.
 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
+* Portable Allocation::         Portable use of @code{malloc}.
 * Freeing after Malloc::        Use @code{free} to free a block you
 				 got with @code{malloc}.
 * Changing Block Size::         Use @code{realloc} to make a block
@@ -621,7 +622,7 @@ If no more space is available, @code{malloc} returns a null pointer.
 You should check the value of @emph{every} call to @code{malloc}.  It is
 useful to write a subroutine that calls @code{malloc} and reports an
 error if the value is a null pointer, returning only if the value is
-nonzero.  This function is conventionally called @code{xmalloc}.  Here
+non-null.  This function is conventionally called @code{xmalloc}.  Here
 it is:
 @cindex @code{xmalloc} function
 
@@ -629,10 +630,10 @@ it is:
 void *
 xmalloc (size_t size)
 @{
-  void *value = malloc (size);
-  if (value == 0)
+  void *p = malloc (size);
+  if (p == NULL)
     fatal ("virtual memory exhausted");
-  return value;
+  return p;
 @}
 @end smallexample
 
@@ -645,9 +646,9 @@ a newly allocated null-terminated string:
 char *
 savestring (const char *ptr, size_t len)
 @{
-  char *value = xmalloc (len + 1);
-  value[len] = '\0';
-  return memcpy (value, ptr, len);
+  char *p = xmalloc (len + 1);
+  p[len] = '\0';
+  return memcpy (p, ptr, len);
 @}
 @end group
 @end smallexample
@@ -669,19 +670,44 @@ contents of another block.  If you have already allocated a block and
 discover you want it to be bigger, use @code{realloc} (@pxref{Changing
 Block Size}).
 
-@strong{Portability Notes:}
+@node Portable Allocation
+@subsubsection Portable Memory Allocation
+
+More care is needed when allocating memory in
+code intended to run on both GNU and non-GNU systems,
+or when a non-GNU replacement allocator is used (@pxref{Replacing malloc}).
+When storage size is small or outlandishly large,
+or when storage is allocated for a less-common type,
+the POSIX and ISO C standards permit multiple behaviors.
 
 @itemize @bullet
 @item
-In @theglibc{}, a successful @code{malloc (0)}
-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.
+In most systems, a successful @code{malloc (0)}
+returns a non-null pointer to a newly allocated size-zero block.
+However, IBM AIX is unusual in that a successful @code{malloc (0)}
+returns a null pointer, and this breaks common code such as the
+implementation of @code{xmalloc} given in this manual.  @xref{Malloc Examples}.
+Code intended to be portable to IBM AIX can use
+@code{p = malloc (size | (size == 0))} instead of @code{p = malloc (size)},
+or if it does not mind a null pointer on success it can replace the following
+@code{if (p == NULL) fatal (...);} with
+@code{if (p == NULL && size != 0) fatal (...);}.
 
 @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
+In @theglibc{}, a failed @code{malloc} call sets @code{errno},
+but ISO C does not require this and non-POSIX implementations
+need not set @code{errno} when failing.
+
+@item
+In @theglibc{}, @code{malloc} always fails when @var{size} exceeds
+@code{PTRDIFF_MAX}, to avoid problems with programs that subtract
+pointers or use signed indexes.  Other implementations may succeed in
+this case, leading to undefined behavior later.
+
+@item
+In @theglibc{}, @code{malloc (@var{size})} returns a pointer that when
+converted to an integer is a multiple of @code{alignof (max_align_t)}.
+Some 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,
@@ -691,15 +717,36 @@ 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
-need not set @code{errno} when failing.
+Although @theglibc{}'s headers define only types with fundamental alignment,
+the C and POSIX standards require only the following types
+(if available) to have fundamental alignment:
+
+@quotation
+@code{char};
+all integer types (including @code{bool});
+@code{float}, @code{double}, @code{long double};
+@code{_Decimal32}, @code{_Decimal64}, @code{_Decimal128};
+@code{float _Complex}, @code{double _Complex}, @code{long double _Complex};
+all enumerated types;
+all pointer types;
+all array types whose element types have fundamental alignment;
+all struct and union types whose element types all have
+fundamental alignment and that lack stricter alignment specifiers;
+@code{va_list} (in @code{<stdarg.h>});
+@code{fpos_t} (in @code{<stdio.h>});
+@code{cnd_t}, @code{thrd_t}, @code{tss_t}, @code{mtx_t}, @code{once_flag}
+(in @code{<threads.h>});
+@code{mbstate_t} (in @code{<wchar.h>}).
+@end quotation
 
-@item
-In @theglibc{}, @code{malloc} always fails when @var{size} exceeds
-@code{PTRDIFF_MAX}, to avoid problems with programs that subtract
-pointers or use signed indexes.  Other implementations may succeed in
-this case, leading to undefined behavior later.
+@noindent
+In theory, portable code should not use @code{malloc} to
+allocate storage containing types not in this list;
+it should instead use functions like @code{aligned_alloc}.
+In practice, though, other implementations generally follow
+@theglibc{}'s lead and define only types with fundamental alignment,
+and it is generally portable to use @code{malloc} to allocate objects
+with types defined by the C library.
 @end itemize
 
 @node Freeing after Malloc
@@ -883,6 +930,8 @@ 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.
+Any special alignment created by @code{aligned_alloc}
+and similar functions is lost after @code{realloc}.
 @end deftypefun
 
 @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
@@ -900,6 +949,13 @@ returning a null pointer, and leaving the original block unchanged.
 @code{reallocarray} should be used instead of @code{realloc} when the new size
 of the allocated block is the result of a multiplication that might overflow.
 
+In @theglibc{}, the vector is aligned the same way that @code{malloc}
+aligns its returned values.  In other implementations, it may be merely
+aligned suitably for any array of fundamentally-aligned elements each
+with size at most @code{max (@var{size}, 1)}.
+Any special alignment created by @code{aligned_alloc}
+and similar functions is lost after @code{reallocarray}.
+
 This function was originally derived from OpenBSD 5.6, but was added in
 POSIX.1-2024.
 @end deftypefun
@@ -922,8 +978,8 @@ as @code{xmalloc} does for @code{malloc}:
 void *
 xreallocarray (void *ptr, size_t nmemb, size_t size)
 @{
-  void *value = reallocarray (ptr, nmemb, size);
-  if (value == 0)
+  void *p = reallocarray (ptr, nmemb, size);
+  if (p == NULL)
     fatal ("Virtual memory exhausted");
   return value;
 @}
@@ -994,15 +1050,9 @@ is declared in @file{stdlib.h}.
 @c  chunk_is_mmapped dup ok
 @c  MALLOC_ZERO ok
 @c   memset dup ok
-This function allocates a block long enough to contain a vector of
-@var{count} elements, each of size @var{eltsize}.  Its contents are
-cleared to zero before @code{calloc} returns.
-
-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)}.
-
+This function allocates a zeroed vector.  It acts like
+@code{reallocarray (NULL, @var{count}, @var{eltsize})} except that the
+vector's contents are cleared to zero before @code{calloc} returns.
 @end deftypefun
 
 You could define @code{calloc} as follows:
@@ -1011,10 +1061,10 @@ You could define @code{calloc} as follows:
 void *
 calloc (size_t count, size_t eltsize)
 @{
-  void *value = reallocarray (0, count, eltsize);
-  if (value != 0)
-    memset (value, 0, count * eltsize);
-  return value;
+  void *p = reallocarray (0, count, eltsize);
+  if (p != NULL)
+    memset (p, 0, count * eltsize);
+  return p;
 @}
 @end smallexample
 
@@ -1934,7 +1984,9 @@ functions (that is, all the functions used by the application,
 failures, and, at run time, to heap corruption and application crashes.
 Replacement functions should implement the behavior documented for
 their counterparts in @theglibc{}; for example, the replacement
-@code{free} should also preserve @code{errno}.
+@code{malloc} should return a null pointer only when failing,
+it should return pointers aligned to @code{alignof (max_align_t)},
+and the replacement @code{free} should preserve @code{errno}.
 
 The minimum set of functions which has to be provided by a custom
 @code{malloc} is given in the table below.
-- 
2.51.0

Re: [PATCH v3 3/4] Say malloc (0) != NULL is now common; resection

[Florian Weimer]

* Paul Eggert:

> * manual/memory.texi (Portable Allocation):
> New section, split off from Malloc Examples.
> Say that almost every system follows glibc's example
> in having successful malloc (0) return non-null;
> AIX is the only exception nowadays.
> Document fundamental alignment portability.
> Have examples match the new text, and use NULL rather than 0.
> ---
>  manual/memory.texi | 130 +++++++++++++++++++++++++++++++--------------
>  1 file changed, 91 insertions(+), 39 deletions(-)
>
> diff --git a/manual/memory.texi b/manual/memory.texi
> index 614cdc4e46..935df79e9c 100644
> --- a/manual/memory.texi
> +++ b/manual/memory.texi
> @@ -318,6 +318,7 @@ any time (or never).
>  @menu
>  * Basic Allocation::            Simple use of @code{malloc}.
>  * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
> +* Portable Allocation::         Portable use of @code{malloc}.
>  * Freeing after Malloc::        Use @code{free} to free a block you
>  				 got with @code{malloc}.
>  * Changing Block Size::         Use @code{realloc} to make a block

Looks okay to me.

Reviewed-by: Florian Weimer <fweimer@redhat.com>

Thanks,
Florian

[PATCH v3 4/4] malloc: alignment might change in future versions

[Paul Eggert]

This follows up on a comment by Wilco Dijkstra; see:
https://sourceware.org/pipermail/libc-alpha/2026-February/174934.html
* NEWS: Mention this.
* manual/lang.texi (Important Data Types):
Say that alignof (max_align_t) might change.
* manual/memory.texi (Malloc Examples):
Say that alignment guarantee might change for small allocations.
---
 NEWS               | 7 ++++++-
 manual/lang.texi   | 2 +-
 manual/memory.texi | 8 ++++++--
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/NEWS b/NEWS
index c63d9d6470..46590a996c 100644
--- a/NEWS
+++ b/NEWS
@@ -13,7 +13,12 @@ Major new features:
 
 Deprecated and removed features, and other changes affecting compatibility:
 
-  [Add deprecations, removals and changes affecting compatibility here]
+* Although malloc and related functions currently return pointers
+  aligned to alignof (max_align_t), the documentation now says future
+  versions of glibc may relax alignment requirements for small allocations.
+  For example, a future malloc (1) might return a pointer with odd
+  alignment, because no object of size 1 can have a fundamental
+  alignment greater than 1.
 
 Changes to build and runtime requirements:
 
diff --git a/manual/lang.texi b/manual/lang.texi
index 28e7de2b2c..925cdacc1f 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -597,7 +597,7 @@ types have a fundamental alignment and lack stricter alignment specifiers.
 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.
+types.  The value may change in future releases.
 
 @strong{Compatibility Note:} The C11 standard introduced @code{max_align_t};
 older compilers may lack the type.
diff --git a/manual/memory.texi b/manual/memory.texi
index 935df79e9c..4f0ef51514 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -653,13 +653,17 @@ savestring (const char *ptr, size_t len)
 @end group
 @end smallexample
 
-In @theglibc{}, the block that @code{malloc} gives you is guaranteed
-to be aligned so that its address is a multiple of
+In the current release of @theglibc{}, the block that @code{malloc} gives you is
+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}).
+Future releases of @theglibc{} may relax alignment for small allocations,
+so long as any object with fundamental alignment that fits in the small
+allocation will be properly aligned.  For example, a future @code{malloc (1)}
+might return a pointer with odd alignment.
 
 Note that the memory located after the end of the block is likely to be
 in use for something else; perhaps a block already allocated by another
-- 
2.51.0

Re: [PATCH v3 4/4] malloc: alignment might change in future versions

[Florian Weimer]

* Paul Eggert:

> diff --git a/manual/lang.texi b/manual/lang.texi
> index 28e7de2b2c..925cdacc1f 100644
> --- a/manual/lang.texi
> +++ b/manual/lang.texi
> @@ -597,7 +597,7 @@ types have a fundamental alignment and lack stricter alignment specifiers.
>  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.
> +types.  The value may change in future releases.

Can we really change the definition of the type, though?  That's close
to an ABI event.

Rest looks okay to me.

Thanks,
Florian

Re: [PATCH v3 4/4] malloc: alignment might change in future versions

[Paul Eggert]

On 2026-02-26 04:47, Florian Weimer wrote:
>> --- a/manual/lang.texi
>> +++ b/manual/lang.texi
>> @@ -597,7 +597,7 @@ types have a fundamental alignment and lack stricter alignment specifiers.
>>   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.
>> +types.  The value may change in future releases.
> Can we really change the definition of the type, though?  That's close
> to an ABI event.
> 
> Rest looks okay to me.

Thanks, I installed the patches without that sentence.

However, the manual should discuss the ABI effect of any possible 
differences in max_align_t, or in intmax_t/uintmax_t for that matter. 
This is relevant partly because C23 (unlike earlier C standards) allows 
intmax_t to be narrower than int128_t (assuming the latter type exists, 
which it really should with GCC).

I'll propose further patches along those lines.

[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

[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

[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>