Debian Codegraph @

upstream/debian-trixie/man3/posix_memalign.3

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