]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
bf5a7247 | 2 | .\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk> |
fea681da MK |
3 | .\" Based in part on GNU libc documentation. |
4 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" 2001-10-11, 2003-08-22, aeb, added some details | |
8f804f14 MK |
8 | .\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com> |
9 | .\" Document pvalloc() and aligned_alloc() | |
4c1c5274 | 10 | .TH posix_memalign 3 (date) "Linux man-pages (unreleased)" |
fea681da | 11 | .SH NAME |
15f0b7af AC |
12 | posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- |
13 | allocate aligned memory | |
7cc1a01f AC |
14 | .SH LIBRARY |
15 | Standard C library | |
8fc3b2cf | 16 | .RI ( libc ", " \-lc ) |
fea681da MK |
17 | .SH SYNOPSIS |
18 | .nf | |
fea681da | 19 | .B #include <stdlib.h> |
c6d039a3 | 20 | .P |
fea681da | 21 | .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); |
8f804f14 | 22 | .BI "void *aligned_alloc(size_t " alignment ", size_t " size ); |
604c5792 | 23 | .BI "[[deprecated]] void *valloc(size_t " size ); |
c6d039a3 | 24 | .P |
fea681da | 25 | .B #include <malloc.h> |
c6d039a3 | 26 | .P |
604c5792 AC |
27 | .BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size ); |
28 | .BI "[[deprecated]] void *pvalloc(size_t " size ); | |
fea681da | 29 | .fi |
c6d039a3 | 30 | .P |
d39ad78f | 31 | .RS -4 |
cc4615cc MK |
32 | Feature Test Macro Requirements for glibc (see |
33 | .BR feature_test_macros (7)): | |
d39ad78f | 34 | .RE |
c6d039a3 | 35 | .P |
cc4615cc | 36 | .BR posix_memalign (): |
9d2adbae | 37 | .nf |
5c10d2c5 | 38 | _POSIX_C_SOURCE >= 200112L |
9d2adbae | 39 | .fi |
c6d039a3 | 40 | .P |
8f804f14 | 41 | .BR aligned_alloc (): |
9d2adbae MK |
42 | .nf |
43 | _ISOC11_SOURCE | |
44 | .fi | |
c6d039a3 | 45 | .P |
124b387f | 46 | .BR valloc (): |
124b387f | 47 | .nf |
9d2adbae | 48 | Since glibc 2.12: |
5c10d2c5 | 49 | (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L) |
75c018a1 AC |
50 | || /* glibc >= 2.19: */ _DEFAULT_SOURCE |
51 | || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE | |
9d2adbae | 52 | Before glibc 2.12: |
5c10d2c5 MK |
53 | _BSD_SOURCE || _XOPEN_SOURCE >= 500 |
54 | .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED | |
9d2adbae | 55 | .fi |
fea681da | 56 | .SH DESCRIPTION |
63aa9df0 | 57 | .BR posix_memalign () |
fea681da MK |
58 | allocates |
59 | .I size | |
60 | bytes and places the address of the allocated memory in | |
a5e0a0e4 | 61 | .IR "*memptr" . |
fea681da | 62 | The address of the allocated memory will be a multiple of |
a5e0a0e4 | 63 | .IR "alignment" , |
fea681da | 64 | which must be a power of two and a multiple of |
5049da5b | 65 | .IR "sizeof(void\ *)" . |
62e2943e BH |
66 | This address can later be successfully passed to |
67 | .BR free (3). | |
b6dd683a MK |
68 | If |
69 | .I size | |
70 | is 0, then | |
558f02df | 71 | the value placed in |
1ae6b2c7 | 72 | .I *memptr |
62e2943e | 73 | is either NULL |
b6dd683a | 74 | .\" glibc does this: |
62e2943e | 75 | or a unique pointer value. |
c6d039a3 | 76 | .P |
fea681da | 77 | The obsolete function |
63aa9df0 | 78 | .BR memalign () |
fea681da MK |
79 | allocates |
80 | .I size | |
81 | bytes and returns a pointer to the allocated memory. | |
82 | The memory address will be a multiple of | |
01657408 | 83 | .IR alignment , |
fea681da | 84 | which must be a power of two. |
0d244df1 MK |
85 | .\" The behavior of memalign() for size==0 is as for posix_memalign() |
86 | .\" but no standards govern this. | |
c6d039a3 | 87 | .P |
8f804f14 MK |
88 | .BR aligned_alloc () |
89 | is the same as | |
90 | .BR memalign (), | |
91 | except for the added restriction that | |
7fd1e0f2 DD |
92 | .I alignment |
93 | must be a power of two. | |
c6d039a3 | 94 | .P |
fea681da | 95 | The obsolete function |
63aa9df0 | 96 | .BR valloc () |
fea681da MK |
97 | allocates |
98 | .I size | |
99 | bytes and returns a pointer to the allocated memory. | |
100 | The memory address will be a multiple of the page size. | |
101 | It is equivalent to | |
102 | .IR "memalign(sysconf(_SC_PAGESIZE),size)" . | |
c6d039a3 | 103 | .P |
59b02287 MK |
104 | The obsolete function |
105 | .BR pvalloc () | |
106 | is similar to | |
107 | .BR valloc (), | |
108 | but rounds the size of the allocation up to | |
109 | the next multiple of the system page size. | |
c6d039a3 | 110 | .P |
59b02287 | 111 | For all of these functions, the memory is not zeroed. |
47297adb | 112 | .SH RETURN VALUE |
8f804f14 | 113 | .BR aligned_alloc (), |
59b02287 MK |
114 | .BR memalign (), |
115 | .BR valloc (), | |
fea681da | 116 | and |
59b02287 | 117 | .BR pvalloc () |
2cfdf8f8 EH |
118 | return a pointer to the allocated memory on success. |
119 | On error, NULL is returned, and \fIerrno\fP is set | |
855d489a | 120 | to indicate the error. |
c6d039a3 | 121 | .P |
63aa9df0 | 122 | .BR posix_memalign () |
fea681da | 123 | returns zero on success, or one of the error values listed in the |
c13182ef | 124 | next section on failure. |
21a1f5bd | 125 | The value of |
0daa9e92 | 126 | .I errno |
df383cdf MK |
127 | is not set. |
128 | On Linux (and other systems), | |
129 | .BR posix_memalign () | |
130 | does not modify | |
131 | .I memptr | |
132 | on failure. | |
5dbd04b5 | 133 | A requirement standardizing this behavior was added in POSIX.1-2008 TC2. |
df383cdf | 134 | .\" http://austingroupbugs.net/view.php?id=520 |
d8026103 | 135 | .SH ERRORS |
fea681da MK |
136 | .TP |
137 | .B EINVAL | |
138 | The | |
0daa9e92 | 139 | .I alignment |
c4bb193f | 140 | argument was not a power of two, or was not a multiple of |
5049da5b | 141 | .IR "sizeof(void\ *)" . |
fea681da MK |
142 | .TP |
143 | .B ENOMEM | |
036fba51 | 144 | Out of memory. |
b63bb31a ZL |
145 | .SH ATTRIBUTES |
146 | For an explanation of the terms used in this section, see | |
147 | .BR attributes (7). | |
148 | .TS | |
149 | allbox; | |
c466875e | 150 | lbx lb lb |
b63bb31a ZL |
151 | l l l. |
152 | Interface Attribute Value | |
153 | T{ | |
9e54434e BR |
154 | .na |
155 | .nh | |
b63bb31a | 156 | .BR aligned_alloc (), |
b63bb31a | 157 | .BR memalign (), |
b63bb31a ZL |
158 | .BR posix_memalign () |
159 | T} Thread safety MT-Safe | |
160 | T{ | |
9e54434e BR |
161 | .na |
162 | .nh | |
b63bb31a | 163 | .BR valloc (), |
b63bb31a ZL |
164 | .BR pvalloc () |
165 | T} Thread safety MT-Unsafe init | |
166 | .TE | |
4131356c AC |
167 | .SH STANDARDS |
168 | .TP | |
169 | .BR aligned_alloc () | |
170 | C11. | |
171 | .TP | |
172 | .BR posix_memalign () | |
173 | POSIX.1-2008. | |
174 | .TP | |
175 | .BR memalign () | |
176 | .TQ | |
177 | .BR valloc () | |
178 | None. | |
179 | .TP | |
196224f7 | 180 | .BR pvalloc () |
4131356c AC |
181 | GNU. |
182 | .SH HISTORY | |
183 | .TP | |
196224f7 | 184 | .BR aligned_alloc () |
4131356c AC |
185 | glibc 2.16. |
186 | C11. | |
187 | .TP | |
196224f7 | 188 | .BR posix_memalign () |
4131356c AC |
189 | glibc 2.1.91. |
190 | POSIX.1d, POSIX.1-2001. | |
191 | .TP | |
192 | .BR memalign () | |
193 | glibc 2.0. | |
194 | SunOS 4.1.3. | |
195 | .TP | |
2b2581ee | 196 | .BR valloc () |
4131356c AC |
197 | glibc 2.0. |
198 | 3.0BSD. | |
199 | Documented as obsolete in 4.3BSD, | |
2b2581ee | 200 | and as legacy in SUSv2. |
4131356c | 201 | .TP |
59b02287 | 202 | .BR pvalloc () |
4131356c | 203 | glibc 2.0. |
8f804f14 | 204 | .\" |
2b2581ee MK |
205 | .SS Headers |
206 | Everybody agrees that | |
207 | .BR posix_memalign () | |
c84371c6 | 208 | is declared in \fI<stdlib.h>\fP. |
c6d039a3 | 209 | .P |
2b2581ee MK |
210 | On some systems |
211 | .BR memalign () | |
c84371c6 | 212 | is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP. |
c6d039a3 | 213 | .P |
2b2581ee MK |
214 | According to SUSv2, |
215 | .BR valloc () | |
c84371c6 | 216 | is declared in \fI<stdlib.h>\fP. |
ebf47ac9 | 217 | .\" Libc4,5 and |
75c018a1 | 218 | glibc declares it in \fI<malloc.h>\fP, and also in |
d9a10d9d | 219 | \fI<stdlib.h>\fP |
287cdf88 | 220 | if suitable feature test macros are defined (see above). |
fea681da | 221 | .SH NOTES |
75b94dc3 | 222 | On many systems there are alignment restrictions, for example, on buffers |
c13182ef MK |
223 | used for direct block device I/O. |
224 | POSIX specifies the | |
fea681da | 225 | .I "pathconf(path,_PC_REC_XFER_ALIGN)" |
c13182ef MK |
226 | call that tells what alignment is needed. |
227 | Now one can use | |
fea681da MK |
228 | .BR posix_memalign () |
229 | to satisfy this requirement. | |
c6d039a3 | 230 | .P |
fea681da MK |
231 | .BR posix_memalign () |
232 | verifies that | |
0daa9e92 | 233 | .I alignment |
fea681da | 234 | matches the requirements detailed above. |
63aa9df0 | 235 | .BR memalign () |
fea681da | 236 | may not check that the |
01657408 | 237 | .I alignment |
c4bb193f | 238 | argument is correct. |
c6d039a3 | 239 | .P |
fea681da | 240 | POSIX requires that memory obtained from |
63aa9df0 | 241 | .BR posix_memalign () |
fea681da | 242 | can be freed using |
fb186734 | 243 | .BR free (3). |
fea681da | 244 | Some systems provide no way to reclaim memory allocated with |
31e9a9ec | 245 | .BR memalign () |
fea681da | 246 | or |
31e9a9ec | 247 | .BR valloc () |
33a0ccb2 | 248 | (because one can pass to |
fb186734 | 249 | .BR free (3) |
33a0ccb2 | 250 | only a pointer obtained from |
fb186734 | 251 | .BR malloc (3), |
75b94dc3 | 252 | while, for example, |
31e9a9ec | 253 | .BR memalign () |
fea681da | 254 | would call |
fb186734 | 255 | .BR malloc (3) |
fea681da MK |
256 | and then align the obtained value). |
257 | .\" Other systems allow passing the result of | |
258 | .\" .IR valloc () | |
259 | .\" to | |
fb186734 | 260 | .\" .IR free (3), |
fea681da | 261 | .\" but not to |
fb186734 | 262 | .\" .IR realloc (3). |
5260fe08 | 263 | The glibc implementation |
b00b80e0 | 264 | allows memory obtained from any of these functions to be |
fea681da | 265 | reclaimed with |
fb186734 | 266 | .BR free (3). |
c6d039a3 | 267 | .P |
5260fe08 | 268 | The glibc |
fb186734 | 269 | .BR malloc (3) |
33a0ccb2 MK |
270 | always returns 8-byte aligned memory addresses, so these functions are |
271 | needed only if you require larger alignment values. | |
47297adb | 272 | .SH SEE ALSO |
fea681da MK |
273 | .BR brk (2), |
274 | .BR getpagesize (2), | |
275 | .BR free (3), | |
cc4615cc | 276 | .BR malloc (3) |