1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
'\" 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 (unreleased)"
.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)
|
