Debian Codegraph @

upstream/debian-unstable/man3/aligned_alloc.3

raw
1 '\" t
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH aligned_alloc 3 2025-12-25 "Linux man-pages 6.18"
7 .SH NAME
8 aligned_alloc
9 \-
10 allocate aligned memory
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <stdlib.h>
17 .P
18 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
19 .fi
20 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR aligned_alloc ():
27 .nf
28 _ISOC11_SOURCE
29 .fi
30 .SH DESCRIPTION
31 .BR aligned_alloc ()
32 allocates
33 .I size
34 bytes and returns a pointer to the allocated memory.
35 The memory address will be a multiple of
36 .IR alignment ,
37 which must be a power of two.
38 This address can later be successfully passed to
39 .BR free (3).
40 .P
41 The memory is not zeroed.
42 .SH RETURN VALUE
43 .BR aligned_alloc ()
44 returns a pointer to the allocated memory on success.
45 On error, NULL is returned, and
46 .I errno
47 is set
48 to indicate the error.
49 .SH ERRORS
50 .TP
51 .B EINVAL
52 The
53 .I alignment
54 argument was not a power of two.
55 .TP
56 .B ENOMEM
57 Out of memory.
58 .SH ATTRIBUTES
59 For an explanation of the terms used in this section, see
60 .BR attributes (7).
61 .TS
62 allbox;
63 lbx lb lb
64 l l l.
65 Interface Attribute Value
66 T{
67 .na
68 .nh
69 .BR aligned_alloc ()
70 T} Thread safety MT-Safe
71 .TE
72 .SH STANDARDS
73 C23,
74 POSIX.1-2024.
75 .SH HISTORY
76 glibc 2.16.
77 C11,
78 POSIX.1-2024.
79 .SS C11
80 In C11,
81 the specification of this function had
82 .UR https:\://port70.net/\:\[ti]nsz/\:c/\:c11/\:n1570.html#7.22.3.1p2
83 several issues
84 .UE .
85 .IP \[bu] 3
86 .I size
87 had to be a multiple of
88 .IR alignment .
89 Otherwise,
90 the behavior was undefined.
91 .IP \[bu]
92 If
93 .I alignment
94 was not a power of two,
95 the behavior was undefined.
96 .P
97 .UR https:\://www.open\-std.org/\:jtc1/\:sc22/\:wg14/\:www/\:docs/\:summary.htm#dr_460
98 DR460
99 .UE
100 reported both cases of UB as unnecessarily dangerous,
101 and fixed them with a Technical Corrigendum
102 that transformed them into errors.
103 .P
104 .UR https:\://www.open\-std.org/\:jtc1/\:sc22/\:wg14/\:www/\:docs/\:n2072.htm
105 N2072
106 .UE
107 reported that the requirement
108 that
109 .I size
110 is a multiple of
111 .I alignment
112 is superfluous,
113 and removed it with a Technical Corrigendum.
114 .P
115 C17 incorporates both technical corrigenda.
116 The API has been stable since C17.
117 .P
118 glibc initially implemented it as silently aligning as
119 .I stdc_bit_ceil(alignment)
120 instead of
121 .IR alignment .
122 Since glibc 2.38,
123 it implements the C17 specification.
124 .P
125 Some implementations,
126 such as FreeBSD/jemalloc,
127 implement the C17 specification,
128 even though their documentation claims having undefined behavior.
129 .P
130 Some implementations,
131 such as OpenBSD,
132 implement C11 amended with DR460,
133 even though their documentation claims having undefined behavior.
134 .P
135 No known implementations
136 have exploited the undefined behavior
137 in a more dangerous way.
138 This function should be safe to use.
139 .SH NOTES
140 On many systems there are alignment restrictions, for example, on buffers
141 used for direct block device I/O.
142 POSIX specifies the
143 .I "pathconf(path,_PC_REC_XFER_ALIGN)"
144 call that tells what alignment is needed.
145 Now one can use
146 .BR aligned_alloc ()
147 to satisfy this requirement.
148 .P
149 The glibc
150 .BR malloc (3)
151 always returns 8-byte aligned memory addresses,
152 so this function is needed
153 only if you require larger alignment values.
154 .SH SEE ALSO
155 .BR brk (2),
156 .BR getpagesize (2),
157 .BR free (3),
158 .BR malloc (3)