1posix_memalign(3) Library Functions Manual posix_memalign(3)
2
6 posix_memalign, aligned_alloc, memalign, valloc, pvalloc - allocate
7 aligned memory
8
10 Standard C library (libc, -lc)
11
13 #include <stdlib.h>
14 int posix_memalign(void **memptr, size_t alignment, size_t size);
16 void *aligned_alloc(size_t alignment, size_t size);
17 [[deprecated]] void *valloc(size_t size);
18 #include <malloc.h>
20 [[deprecated]] void *memalign(size_t alignment, size_t size);
22 [[deprecated]] void *pvalloc(size_t size);
23 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
25 posix_memalign():
27 _POSIX_C_SOURCE >= 200112L
28 aligned_alloc():
30 _ISOC11_SOURCE
31 valloc():
33 Since glibc 2.12:
34 (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
35 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
36 || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
37 Before glibc 2.12:
38 _BSD_SOURCE || _XOPEN_SOURCE >= 500
39
41 The function posix_memalign() allocates size bytes and places the ad‐
42 dress of the allocated memory in *memptr. The address of the allocated
43 memory will be a multiple of alignment, which must be a power of two
44 and a multiple of sizeof(void *). This address can later be success‐
45 fully passed to free(3). If size is 0, then the value placed in
46 *memptr is either NULL or a unique pointer value.
47 The obsolete function memalign() allocates size bytes and returns a
49 pointer to the allocated memory. The memory address will be a multiple
50 of alignment, which must be a power of two.
51 The function aligned_alloc() is the same as memalign(), except for the
53 added restriction that size should be a multiple of alignment.
54 The obsolete function valloc() allocates size bytes and returns a
56 pointer to the allocated memory. The memory address will be a multiple
57 of the page size. It is equivalent to memalign(sysconf(_SC_PAGE‐
58 SIZE),size).
59 The obsolete function pvalloc() is similar to valloc(), but rounds the
61 size of the allocation up to the next multiple of the system page size.
62 For all of these functions, the memory is not zeroed.
64
66 aligned_alloc(), memalign(), valloc(), and pvalloc() return a pointer
67 to the allocated memory on success. On error, NULL is returned, and
68 errno is set to indicate the error.
69 posix_memalign() returns zero on success, or one of the error values
71 listed in the next section on failure. The value of errno is not set.
72 On Linux (and other systems), posix_memalign() does not modify memptr
73 on failure. A requirement standardizing this behavior was added in
74 POSIX.1-2008 TC2.
75
77 EINVAL The alignment argument was not a power of two, or was not a mul‐
78 tiple of sizeof(void *).
79 ENOMEM There was insufficient memory to fulfill the allocation request.
81
83 For an explanation of the terms used in this section, see at‐
84 tributes(7).
85 ┌─────────────────────────────────────┬───────────────┬────────────────┐
87 │Interface │ Attribute │ Value │
88 ├─────────────────────────────────────┼───────────────┼────────────────┤
89 │aligned_alloc(), memalign(), │ Thread safety │ MT-Safe │
90 │posix_memalign() │ │ │
91 ├─────────────────────────────────────┼───────────────┼────────────────┤
92 │valloc(), pvalloc() │ Thread safety │ MT-Unsafe init │
93 └─────────────────────────────────────┴───────────────┴────────────────┘
94
96 aligned_alloc()
97 C11.
98 posix_memalign()
100 POSIX.1-2008.
101 memalign()
103 valloc()
104 None.
105 pvalloc()
107 GNU.
108
110 aligned_alloc()
111 glibc 2.16. C11.
112 posix_memalign()
114 glibc 2.1.91. POSIX.1d, POSIX.1-2001.
115 memalign()
117 glibc 2.0. SunOS 4.1.3.
118 valloc()
120 glibc 2.0. 3.0BSD. Documented as obsolete in 4.3BSD, and as
121 legacy in SUSv2.
122 pvalloc()
124 glibc 2.0.
125 Headers
127 Everybody agrees that posix_memalign() is declared in <stdlib.h>.
128 On some systems memalign() is declared in <stdlib.h> instead of <mal‐
130 loc.h>.
131 According to SUSv2, valloc() is declared in <stdlib.h>. glibc declares
133 it in <malloc.h>, and also in <stdlib.h> if suitable feature test
134 macros are defined (see above).
135
137 On many systems there are alignment restrictions, for example, on buf‐
138 fers used for direct block device I/O. POSIX specifies the path‐
139 conf(path,_PC_REC_XFER_ALIGN) call that tells what alignment is needed.
140 Now one can use posix_memalign() to satisfy this requirement.
141 posix_memalign() verifies that alignment matches the requirements de‐
143 tailed above. memalign() may not check that the alignment argument is
144 correct.
145 POSIX requires that memory obtained from posix_memalign() can be freed
147 using free(3). Some systems provide no way to reclaim memory allocated
148 with memalign() or valloc() (because one can pass to free(3) only a
149 pointer obtained from malloc(3), while, for example, memalign() would
150 call malloc(3) and then align the obtained value). The glibc implemen‐
151 tation allows memory obtained from any of these functions to be re‐
152 claimed with free(3).
153 The glibc malloc(3) always returns 8-byte aligned memory addresses, so
155 these functions are needed only if you require larger alignment values.
156
158 brk(2), getpagesize(2), free(3), malloc(3)
159Linux man-pages 6.04 2023-03-30 posix_memalign(3)