]>
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() | |
287cdf88 | 29 | .TH POSIX_MEMALIGN 3 2012-03-23 "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 MK |
34 | .B #include <stdlib.h> |
35 | .sp | |
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 ); |
fea681da MK |
39 | .sp |
40 | .B #include <malloc.h> | |
41 | .sp | |
01657408 | 42 | .BI "void *memalign(size_t " alignment ", size_t " size ); |
59b02287 | 43 | .BI "void *pvalloc(size_t " size ); |
fea681da | 44 | .fi |
cc4615cc MK |
45 | .sp |
46 | .in -4n | |
47 | Feature Test Macro Requirements for glibc (see | |
48 | .BR feature_test_macros (7)): | |
49 | .in | |
50 | .sp | |
51 | .ad l | |
52 | .BR posix_memalign (): | |
53 | _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600 | |
124b387f | 54 | .sp |
8f804f14 MK |
55 | .BR aligned_alloc (): |
56 | _ISOC11_SOURCE | |
57 | .sp | |
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 MK |
64 | .nf |
65 | _BSD_SOURCE || | |
f6b326eb | 66 | (_XOPEN_SOURCE\ >=\ 500 || |
7b072c4d | 67 | _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) && |
98dbe7af | 68 | !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600) |
124b387f MK |
69 | .br |
70 | .fi | |
71 | .TP | |
72 | Before glibc 2.12: | |
98dbe7af | 73 | _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 || |
124b387f | 74 | _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED |
287cdf88 MK |
75 | .ad b |
76 | .br | |
77 | (The (nonstandard) header file | |
78 | .I <malloc.h> | |
79 | also exposes the declaration of | |
80 | .BR valloc (); | |
81 | no feature test macros are required.) | |
124b387f | 82 | .RE |
e68ab40d | 83 | .PD |
fea681da MK |
84 | .SH DESCRIPTION |
85 | The function | |
63aa9df0 | 86 | .BR posix_memalign () |
fea681da MK |
87 | allocates |
88 | .I size | |
89 | bytes and places the address of the allocated memory in | |
a5e0a0e4 | 90 | .IR "*memptr" . |
fea681da | 91 | The address of the allocated memory will be a multiple of |
a5e0a0e4 | 92 | .IR "alignment" , |
fea681da | 93 | which must be a power of two and a multiple of |
5049da5b | 94 | .IR "sizeof(void\ *)" . |
b6dd683a MK |
95 | If |
96 | .I size | |
97 | is 0, then | |
98 | .BR posix_memalign () | |
99 | returns either NULL, | |
100 | .\" glibc does this: | |
101 | or a unique pointer value that can later be successfully passed to | |
0b80cf56 | 102 | .BR free (3). |
fea681da MK |
103 | |
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. | |
fea681da | 114 | |
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 . | |
123 | ||
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)" . | |
132 | ||
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. | |
139 | ||
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. | |
fea681da | 148 | |
63aa9df0 | 149 | .BR posix_memalign () |
fea681da | 150 | returns zero on success, or one of the error values listed in the |
c13182ef MK |
151 | next section on failure. |
152 | Note that | |
0daa9e92 | 153 | .I errno |
fea681da | 154 | is not set. |
47297adb | 155 | .SH ERRORS |
fea681da MK |
156 | .TP |
157 | .B EINVAL | |
158 | The | |
0daa9e92 | 159 | .I alignment |
c4bb193f | 160 | argument was not a power of two, or was not a multiple of |
5049da5b | 161 | .IR "sizeof(void\ *)" . |
fea681da MK |
162 | .TP |
163 | .B ENOMEM | |
164 | There was insufficient memory to fulfill the allocation request. | |
2b2581ee MK |
165 | .SH VERSIONS |
166 | The functions | |
59b02287 MK |
167 | .BR memalign (), |
168 | .BR valloc (), | |
2b2581ee | 169 | and |
59b02287 | 170 | .BR pvalloc () |
2b2581ee | 171 | have been available in all Linux libc libraries. |
8f804f14 MK |
172 | |
173 | The function | |
174 | .BR aligned_alloc () | |
175 | was added to glibc in version 2.16. | |
176 | ||
2b2581ee MK |
177 | The function |
178 | .BR posix_memalign () | |
179 | is available since glibc 2.1.91. | |
47297adb | 180 | .SH CONFORMING TO |
2b2581ee MK |
181 | The function |
182 | .BR valloc () | |
183 | appeared in 3.0BSD. | |
184 | It is documented as being obsolete in 4.3BSD, | |
185 | and as legacy in SUSv2. | |
186 | It does not appear in POSIX.1-2001. | |
c36b9932 | 187 | |
59b02287 MK |
188 | The function |
189 | .BR pvalloc () | |
190 | is a GNU extension. | |
191 | ||
2b2581ee MK |
192 | The function |
193 | .BR memalign () | |
194 | appears in SunOS 4.1.3 but not in 4.4BSD. | |
c36b9932 | 195 | |
2b2581ee MK |
196 | The function |
197 | .BR posix_memalign () | |
198 | comes from POSIX.1d. | |
8f804f14 MK |
199 | |
200 | The function | |
ebca85d8 | 201 | .BR aligned_alloc () |
8f804f14 MK |
202 | is specified in the C11 standard. |
203 | .\" | |
2b2581ee MK |
204 | .SS Headers |
205 | Everybody agrees that | |
206 | .BR posix_memalign () | |
c84371c6 | 207 | is declared in \fI<stdlib.h>\fP. |
2b2581ee MK |
208 | |
209 | On some systems | |
210 | .BR memalign () | |
c84371c6 | 211 | is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP. |
2b2581ee MK |
212 | |
213 | According to SUSv2, | |
214 | .BR valloc () | |
c84371c6 | 215 | is declared in \fI<stdlib.h>\fP. |
287cdf88 | 216 | Libc4,5 and glibc declare it in \fI<malloc.h>\fP, and also in |
d9a10d9d | 217 | \fI<stdlib.h>\fP |
287cdf88 | 218 | if suitable feature test macros are defined (see above). |
fea681da | 219 | .SH NOTES |
75b94dc3 | 220 | On many systems there are alignment restrictions, for example, on buffers |
c13182ef MK |
221 | used for direct block device I/O. |
222 | POSIX specifies the | |
fea681da | 223 | .I "pathconf(path,_PC_REC_XFER_ALIGN)" |
c13182ef MK |
224 | call that tells what alignment is needed. |
225 | Now one can use | |
fea681da MK |
226 | .BR posix_memalign () |
227 | to satisfy this requirement. | |
228 | ||
229 | .BR posix_memalign () | |
230 | verifies that | |
0daa9e92 | 231 | .I alignment |
fea681da | 232 | matches the requirements detailed above. |
63aa9df0 | 233 | .BR memalign () |
fea681da | 234 | may not check that the |
01657408 | 235 | .I alignment |
c4bb193f | 236 | argument is correct. |
fea681da MK |
237 | |
238 | POSIX requires that memory obtained from | |
63aa9df0 | 239 | .BR posix_memalign () |
fea681da | 240 | can be freed using |
fb186734 | 241 | .BR free (3). |
fea681da | 242 | Some systems provide no way to reclaim memory allocated with |
31e9a9ec | 243 | .BR memalign () |
fea681da | 244 | or |
31e9a9ec | 245 | .BR valloc () |
33a0ccb2 | 246 | (because one can pass to |
fb186734 | 247 | .BR free (3) |
33a0ccb2 | 248 | only a pointer obtained from |
fb186734 | 249 | .BR malloc (3), |
75b94dc3 | 250 | while, for example, |
31e9a9ec | 251 | .BR memalign () |
fea681da | 252 | would call |
fb186734 | 253 | .BR malloc (3) |
fea681da MK |
254 | and then align the obtained value). |
255 | .\" Other systems allow passing the result of | |
256 | .\" .IR valloc () | |
257 | .\" to | |
fb186734 | 258 | .\" .IR free (3), |
fea681da | 259 | .\" but not to |
fb186734 | 260 | .\" .IR realloc (3). |
5260fe08 | 261 | The glibc implementation |
b00b80e0 | 262 | allows memory obtained from any of these functions to be |
fea681da | 263 | reclaimed with |
fb186734 | 264 | .BR free (3). |
fea681da | 265 | |
5260fe08 | 266 | The glibc |
fb186734 | 267 | .BR malloc (3) |
33a0ccb2 MK |
268 | always returns 8-byte aligned memory addresses, so these functions are |
269 | needed only if you require larger alignment values. | |
47297adb | 270 | .SH SEE ALSO |
fea681da MK |
271 | .BR brk (2), |
272 | .BR getpagesize (2), | |
273 | .BR free (3), | |
cc4615cc | 274 | .BR malloc (3) |