]>
Commit | Line | Data |
---|---|---|
bf5a7247 | 1 | .\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk> |
fea681da MK |
2 | .\" Based in part on GNU libc documentation. |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" 2001-10-11, 2003-08-22, aeb, added some details | |
8f804f14 MK |
27 | .\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com> |
28 | .\" Document pvalloc() and aligned_alloc() | |
4b8c67d9 | 29 | .TH POSIX_MEMALIGN 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da | 30 | .SH NAME |
f68512e9 | 31 | posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- allocate aligned memory |
fea681da MK |
32 | .SH SYNOPSIS |
33 | .nf | |
fea681da | 34 | .B #include <stdlib.h> |
68e4db0a | 35 | .PP |
fea681da | 36 | .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); |
8f804f14 | 37 | .BI "void *aligned_alloc(size_t " alignment ", size_t " size ); |
287cdf88 | 38 | .BI "void *valloc(size_t " size ); |
f90f031e | 39 | |
fea681da | 40 | .B #include <malloc.h> |
68e4db0a | 41 | .PP |
01657408 | 42 | .BI "void *memalign(size_t " alignment ", size_t " size ); |
59b02287 | 43 | .BI "void *pvalloc(size_t " size ); |
fea681da | 44 | .fi |
68e4db0a | 45 | .PP |
cc4615cc MK |
46 | .in -4n |
47 | Feature Test Macro Requirements for glibc (see | |
48 | .BR feature_test_macros (7)): | |
49 | .in | |
68e4db0a | 50 | .PP |
cc4615cc MK |
51 | .ad l |
52 | .BR posix_memalign (): | |
a446ac0c | 53 | _POSIX_C_SOURCE\ >=\ 200112L |
68e4db0a | 54 | .PP |
8f804f14 MK |
55 | .BR aligned_alloc (): |
56 | _ISOC11_SOURCE | |
68e4db0a | 57 | .PP |
124b387f MK |
58 | .BR valloc (): |
59 | .br | |
e68ab40d | 60 | .PD 0 |
124b387f MK |
61 | .RS 4 |
62 | .TP 4 | |
f6b326eb | 63 | Since glibc 2.12: |
124b387f | 64 | .nf |
2b1b0424 MK |
65 | (_XOPEN_SOURCE\ >=\ 500) && !(_POSIX_C_SOURCE\ >=\ 200112L) |
66 | || /* Glibc since 2.19: */ _DEFAULT_SOURCE | |
67 | || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE | |
124b387f MK |
68 | .br |
69 | .fi | |
70 | .TP | |
71 | Before glibc 2.12: | |
cf7fa0a1 MK |
72 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 |
73 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
287cdf88 MK |
74 | .ad b |
75 | .br | |
76 | (The (nonstandard) header file | |
77 | .I <malloc.h> | |
78 | also exposes the declaration of | |
79 | .BR valloc (); | |
80 | no feature test macros are required.) | |
124b387f | 81 | .RE |
e68ab40d | 82 | .PD |
fea681da MK |
83 | .SH DESCRIPTION |
84 | The function | |
63aa9df0 | 85 | .BR posix_memalign () |
fea681da MK |
86 | allocates |
87 | .I size | |
88 | bytes and places the address of the allocated memory in | |
a5e0a0e4 | 89 | .IR "*memptr" . |
fea681da | 90 | The address of the allocated memory will be a multiple of |
a5e0a0e4 | 91 | .IR "alignment" , |
fea681da | 92 | which must be a power of two and a multiple of |
5049da5b | 93 | .IR "sizeof(void\ *)" . |
b6dd683a MK |
94 | If |
95 | .I size | |
96 | is 0, then | |
558f02df MK |
97 | the value placed in |
98 | .IR "*memptr" | |
99 | is either NULL, | |
b6dd683a MK |
100 | .\" glibc does this: |
101 | or a unique pointer value that can later be successfully passed to | |
0b80cf56 | 102 | .BR free (3). |
847e0d88 | 103 | .PP |
fea681da | 104 | The obsolete function |
63aa9df0 | 105 | .BR memalign () |
fea681da MK |
106 | allocates |
107 | .I size | |
108 | bytes and returns a pointer to the allocated memory. | |
109 | The memory address will be a multiple of | |
01657408 | 110 | .IR alignment , |
fea681da | 111 | which must be a power of two. |
0d244df1 MK |
112 | .\" The behavior of memalign() for size==0 is as for posix_memalign() |
113 | .\" but no standards govern this. | |
847e0d88 | 114 | .PP |
8f804f14 MK |
115 | The function |
116 | .BR aligned_alloc () | |
117 | is the same as | |
118 | .BR memalign (), | |
119 | except for the added restriction that | |
120 | .I size | |
121 | should be a multiple of | |
122 | .IR alignment . | |
847e0d88 | 123 | .PP |
fea681da | 124 | The obsolete function |
63aa9df0 | 125 | .BR valloc () |
fea681da MK |
126 | allocates |
127 | .I size | |
128 | bytes and returns a pointer to the allocated memory. | |
129 | The memory address will be a multiple of the page size. | |
130 | It is equivalent to | |
131 | .IR "memalign(sysconf(_SC_PAGESIZE),size)" . | |
847e0d88 | 132 | .PP |
59b02287 MK |
133 | The obsolete function |
134 | .BR pvalloc () | |
135 | is similar to | |
136 | .BR valloc (), | |
137 | but rounds the size of the allocation up to | |
138 | the next multiple of the system page size. | |
847e0d88 | 139 | .PP |
59b02287 | 140 | For all of these functions, the memory is not zeroed. |
47297adb | 141 | .SH RETURN VALUE |
8f804f14 | 142 | .BR aligned_alloc (), |
59b02287 MK |
143 | .BR memalign (), |
144 | .BR valloc (), | |
fea681da | 145 | and |
59b02287 MK |
146 | .BR pvalloc () |
147 | return a pointer to the allocated memory, or NULL if the request fails. | |
847e0d88 | 148 | .PP |
63aa9df0 | 149 | .BR posix_memalign () |
fea681da | 150 | returns zero on success, or one of the error values listed in the |
c13182ef | 151 | next section on failure. |
21a1f5bd | 152 | The value of |
0daa9e92 | 153 | .I errno |
df383cdf MK |
154 | is not set. |
155 | On Linux (and other systems), | |
156 | .BR posix_memalign () | |
157 | does not modify | |
158 | .I memptr | |
159 | on failure. | |
160 | A requirement standardizing this behavior was added in POSIX.1-2016. | |
161 | .\" http://austingroupbugs.net/view.php?id=520 | |
d8026103 | 162 | .SH ERRORS |
fea681da MK |
163 | .TP |
164 | .B EINVAL | |
165 | The | |
0daa9e92 | 166 | .I alignment |
c4bb193f | 167 | argument was not a power of two, or was not a multiple of |
5049da5b | 168 | .IR "sizeof(void\ *)" . |
fea681da MK |
169 | .TP |
170 | .B ENOMEM | |
171 | There was insufficient memory to fulfill the allocation request. | |
2b2581ee MK |
172 | .SH VERSIONS |
173 | The functions | |
59b02287 MK |
174 | .BR memalign (), |
175 | .BR valloc (), | |
2b2581ee | 176 | and |
59b02287 | 177 | .BR pvalloc () |
2b2581ee | 178 | have been available in all Linux libc libraries. |
847e0d88 | 179 | .PP |
8f804f14 MK |
180 | The function |
181 | .BR aligned_alloc () | |
182 | was added to glibc in version 2.16. | |
847e0d88 | 183 | .PP |
2b2581ee MK |
184 | The function |
185 | .BR posix_memalign () | |
186 | is available since glibc 2.1.91. | |
b63bb31a ZL |
187 | .SH ATTRIBUTES |
188 | For an explanation of the terms used in this section, see | |
189 | .BR attributes (7). | |
190 | .TS | |
191 | allbox; | |
192 | lb lb lb | |
193 | l l l. | |
194 | Interface Attribute Value | |
195 | T{ | |
196 | .BR aligned_alloc (), | |
197 | .br | |
198 | .BR memalign (), | |
199 | .br | |
200 | .BR posix_memalign () | |
201 | T} Thread safety MT-Safe | |
202 | T{ | |
203 | .BR valloc (), | |
204 | .br | |
205 | .BR pvalloc () | |
206 | T} Thread safety MT-Unsafe init | |
207 | .TE | |
847e0d88 | 208 | .sp 1 |
47297adb | 209 | .SH CONFORMING TO |
2b2581ee MK |
210 | The function |
211 | .BR valloc () | |
212 | appeared in 3.0BSD. | |
213 | It is documented as being obsolete in 4.3BSD, | |
214 | and as legacy in SUSv2. | |
f3924c78 | 215 | It does not appear in POSIX.1. |
847e0d88 | 216 | .PP |
59b02287 MK |
217 | The function |
218 | .BR pvalloc () | |
219 | is a GNU extension. | |
847e0d88 | 220 | .PP |
2b2581ee MK |
221 | The function |
222 | .BR memalign () | |
223 | appears in SunOS 4.1.3 but not in 4.4BSD. | |
847e0d88 | 224 | .PP |
2b2581ee MK |
225 | The function |
226 | .BR posix_memalign () | |
dc90f4d3 | 227 | comes from POSIX.1d and is specified in POSIX.1-2001 and POSIX.1-2008. |
847e0d88 | 228 | .PP |
8f804f14 | 229 | The function |
ebca85d8 | 230 | .BR aligned_alloc () |
8f804f14 MK |
231 | is specified in the C11 standard. |
232 | .\" | |
2b2581ee MK |
233 | .SS Headers |
234 | Everybody agrees that | |
235 | .BR posix_memalign () | |
c84371c6 | 236 | is declared in \fI<stdlib.h>\fP. |
847e0d88 | 237 | .PP |
2b2581ee MK |
238 | On some systems |
239 | .BR memalign () | |
c84371c6 | 240 | is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP. |
847e0d88 | 241 | .PP |
2b2581ee MK |
242 | According to SUSv2, |
243 | .BR valloc () | |
c84371c6 | 244 | is declared in \fI<stdlib.h>\fP. |
287cdf88 | 245 | Libc4,5 and glibc declare it in \fI<malloc.h>\fP, and also in |
d9a10d9d | 246 | \fI<stdlib.h>\fP |
287cdf88 | 247 | if suitable feature test macros are defined (see above). |
fea681da | 248 | .SH NOTES |
75b94dc3 | 249 | On many systems there are alignment restrictions, for example, on buffers |
c13182ef MK |
250 | used for direct block device I/O. |
251 | POSIX specifies the | |
fea681da | 252 | .I "pathconf(path,_PC_REC_XFER_ALIGN)" |
c13182ef MK |
253 | call that tells what alignment is needed. |
254 | Now one can use | |
fea681da MK |
255 | .BR posix_memalign () |
256 | to satisfy this requirement. | |
847e0d88 | 257 | .PP |
fea681da MK |
258 | .BR posix_memalign () |
259 | verifies that | |
0daa9e92 | 260 | .I alignment |
fea681da | 261 | matches the requirements detailed above. |
63aa9df0 | 262 | .BR memalign () |
fea681da | 263 | may not check that the |
01657408 | 264 | .I alignment |
c4bb193f | 265 | argument is correct. |
847e0d88 | 266 | .PP |
fea681da | 267 | POSIX requires that memory obtained from |
63aa9df0 | 268 | .BR posix_memalign () |
fea681da | 269 | can be freed using |
fb186734 | 270 | .BR free (3). |
fea681da | 271 | Some systems provide no way to reclaim memory allocated with |
31e9a9ec | 272 | .BR memalign () |
fea681da | 273 | or |
31e9a9ec | 274 | .BR valloc () |
33a0ccb2 | 275 | (because one can pass to |
fb186734 | 276 | .BR free (3) |
33a0ccb2 | 277 | only a pointer obtained from |
fb186734 | 278 | .BR malloc (3), |
75b94dc3 | 279 | while, for example, |
31e9a9ec | 280 | .BR memalign () |
fea681da | 281 | would call |
fb186734 | 282 | .BR malloc (3) |
fea681da MK |
283 | and then align the obtained value). |
284 | .\" Other systems allow passing the result of | |
285 | .\" .IR valloc () | |
286 | .\" to | |
fb186734 | 287 | .\" .IR free (3), |
fea681da | 288 | .\" but not to |
fb186734 | 289 | .\" .IR realloc (3). |
5260fe08 | 290 | The glibc implementation |
b00b80e0 | 291 | allows memory obtained from any of these functions to be |
fea681da | 292 | reclaimed with |
fb186734 | 293 | .BR free (3). |
847e0d88 | 294 | .PP |
5260fe08 | 295 | The glibc |
fb186734 | 296 | .BR malloc (3) |
33a0ccb2 MK |
297 | always returns 8-byte aligned memory addresses, so these functions are |
298 | needed only if you require larger alignment values. | |
47297adb | 299 | .SH SEE ALSO |
fea681da MK |
300 | .BR brk (2), |
301 | .BR getpagesize (2), | |
302 | .BR free (3), | |
cc4615cc | 303 | .BR malloc (3) |