table of contents
| aligned_alloc(3) | Library Functions Manual | aligned_alloc(3) |
NAME¶
aligned_alloc - allocate aligned memory
LIBRARY¶
Standard C library (libc, -lc)
SYNOPSIS¶
#include <stdlib.h>
void *aligned_alloc(size_t alignment, size_t size);
aligned_alloc():
_ISOC11_SOURCE
DESCRIPTION¶
aligned_alloc() allocates size bytes and returns a pointer to the allocated memory. The memory address will be a multiple of alignment, which must be a power of two. This address can later be successfully passed to free(3).
The memory is not zeroed.
RETURN VALUE¶
aligned_alloc() returns a pointer to the allocated memory on success. On error, NULL is returned, and errno is set to indicate the error.
ERRORS¶
ATTRIBUTES¶
For an explanation of the terms used in this section, see attributes(7).
| Interface | Attribute | Value |
| aligned_alloc () | Thread safety | MT-Safe |
STANDARDS¶
C23, POSIX.1-2024.
HISTORY¶
glibc 2.16. C11, POSIX.1-2024.
C11¶
In C11, the specification of this function had several issues.
- •
- size had to be a multiple of alignment. Otherwise, the behavior was undefined.
- •
- If alignment was not a power of two, the behavior was undefined.
DR460 reported both cases of UB as unnecessarily dangerous, and fixed them with a Technical Corrigendum that transformed them into errors.
N2072 reported that the requirement that size is a multiple of alignment is superfluous, and removed it with a Technical Corrigendum.
C17 incorporates both technical corrigenda. The API has been stable since C17.
glibc initially implemented it as silently aligning as stdc_bit_ceil(alignment) instead of alignment. Since glibc 2.38, it implements the C17 specification.
Some implementations, such as FreeBSD/jemalloc, implement the C17 specification, even though their documentation claims having undefined behavior.
Some implementations, such as OpenBSD, implement C11 amended with DR460, even though their documentation claims having undefined behavior.
No known implementations have exploited the undefined behavior in a more dangerous way. This function should be safe to use.
NOTES¶
On many systems there are alignment restrictions, for example, on buffers used for direct block device I/O. POSIX specifies the pathconf(path,_PC_REC_XFER_ALIGN) call that tells what alignment is needed. Now one can use aligned_alloc() to satisfy this requirement.
The glibc malloc(3) always returns 8-byte aligned memory addresses, so this function is needed only if you require larger alignment values.
SEE ALSO¶
| 2025-12-25 | Linux man-pages 6.17 |