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