'\" t
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH aligned_alloc 3 2025-12-25 "Linux man-pages 6.18"
.SH NAME
aligned_alloc
\-
allocate aligned memory
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
.P
.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
.fi
.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
.P
.BR aligned_alloc ():
.nf
    _ISOC11_SOURCE
.fi
.SH DESCRIPTION
.BR aligned_alloc ()
allocates
.I size
bytes and returns a pointer to the allocated memory.
The memory address will be a multiple of
.IR alignment ,
which must be a power of two.
This address can later be successfully passed to
.BR free (3).
.P
The memory is not zeroed.
.SH RETURN VALUE
.BR aligned_alloc ()
returns a pointer to the allocated memory on success.
On error, NULL is returned, and
.I errno
is set
to indicate the error.
.SH ERRORS
.TP
.B EINVAL
The
.I alignment
argument was not a power of two.
.TP
.B ENOMEM
Out of memory.
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR aligned_alloc ()
T}	Thread safety	MT-Safe
.TE
.SH STANDARDS
C23,
POSIX.1-2024.
.SH HISTORY
glibc 2.16.
C11,
POSIX.1-2024.
.SS C11
In C11,
the specification of this function had
.UR https:\://port70.net/\:\[ti]nsz/\:c/\:c11/\:n1570.html#7.22.3.1p2
several issues
.UE .
.IP \[bu] 3
.I size
had to be a multiple of
.IR alignment .
Otherwise,
the behavior was undefined.
.IP \[bu]
If
.I alignment
was not a power of two,
the behavior was undefined.
.P
.UR https:\://www.open\-std.org/\:jtc1/\:sc22/\:wg14/\:www/\:docs/\:summary.htm#dr_460
DR460
.UE
reported both cases of UB as unnecessarily dangerous,
and fixed them with a Technical Corrigendum
that transformed them into errors.
.P
.UR https:\://www.open\-std.org/\:jtc1/\:sc22/\:wg14/\:www/\:docs/\:n2072.htm
N2072
.UE
reported that the requirement
that
.I size
is a multiple of
.I alignment
is superfluous,
and removed it with a Technical Corrigendum.
.P
C17 incorporates both technical corrigenda.
The API has been stable since C17.
.P
glibc initially implemented it as silently aligning as
.I stdc_bit_ceil(alignment)
instead of
.IR alignment .
Since glibc 2.38,
it implements the C17 specification.
.P
Some implementations,
such as FreeBSD/jemalloc,
implement the C17 specification,
even though their documentation claims having undefined behavior.
.P
Some implementations,
such as OpenBSD,
implement C11 amended with DR460,
even though their documentation claims having undefined behavior.
.P
No known implementations
have exploited the undefined behavior
in a more dangerous way.
This function should be safe to use.
.SH NOTES
On many systems there are alignment restrictions, for example, on buffers
used for direct block device I/O.
POSIX specifies the
.I "pathconf(path,_PC_REC_XFER_ALIGN)"
call that tells what alignment is needed.
Now one can use
.BR aligned_alloc ()
to satisfy this requirement.
.P
The glibc
.BR malloc (3)
always returns 8-byte aligned memory addresses,
so this function is needed
only if you require larger alignment values.
.SH SEE ALSO
.BR brk (2),
.BR getpagesize (2),
.BR free (3),
.BR malloc (3)