1POSIX_MEMALIGN(3)          Linux Programmer's Manual         POSIX_MEMALIGN(3)
2
3
4

NAME

6       posix_memalign,  aligned_alloc,  memalign,  valloc,  pvalloc - allocate
7       aligned memory
8

SYNOPSIS

10       #include <stdlib.h>
11
12       int posix_memalign(void **memptr, size_t alignment, size_t size);
13       void *aligned_alloc(size_t alignment, size_t size);
14       void *valloc(size_t size);
15
16       #include <malloc.h>
17
18       void *memalign(size_t alignment, size_t size);
19       void *pvalloc(size_t size);
20
21   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22
23       posix_memalign(): _POSIX_C_SOURCE >= 200112L
24
25       aligned_alloc(): _ISOC11_SOURCE
26
27       valloc():
28           Since glibc 2.12:
29               (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
30                   || /* Glibc since 2.19: */ _DEFAULT_SOURCE
31                   || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
32           Before glibc 2.12:
33               _BSD_SOURCE || _XOPEN_SOURCE >= 500
34               (The (nonstandard) header file <malloc.h> also exposes the dec‐
35               laration of valloc(); no feature test macros are required.)
36

DESCRIPTION

38       The  function  posix_memalign()  allocates  size  bytes  and places the
39       address of the allocated memory in *memptr.  The address of  the  allo‐
40       cated  memory will be a multiple of alignment, which must be a power of
41       two and a multiple of sizeof(void *).  If size is  0,  then  the  value
42       placed  in  *memptr  is either NULL, or a unique pointer value that can
43       later be successfully passed to free(3).
44
45       The obsolete function memalign() allocates size  bytes  and  returns  a
46       pointer to the allocated memory.  The memory address will be a multiple
47       of alignment, which must be a power of two.
48
49       The function aligned_alloc() is the same as memalign(), except for  the
50       added restriction that size should be a multiple of alignment.
51
52       The  obsolete  function  valloc()  allocates  size  bytes and returns a
53       pointer to the allocated memory.  The memory address will be a multiple
54       of  the  page  size.   It  is  equivalent to memalign(sysconf(_SC_PAGE‐
55       SIZE),size).
56
57       The obsolete function pvalloc() is similar to valloc(), but rounds  the
58       size of the allocation up to the next multiple of the system page size.
59
60       For all of these functions, the memory is not zeroed.
61

RETURN VALUE

63       aligned_alloc(),  memalign(),  valloc(), and pvalloc() return a pointer
64       to the allocated memory on success.  On error, NULL  is  returned,  and
65       errno is set to indicate the cause of the error.
66
67       posix_memalign()  returns  zero  on success, or one of the error values
68       listed in the next section on failure.  The value of errno is not  set.
69       On  Linux  (and other systems), posix_memalign() does not modify memptr
70       on failure.  A requirement standardizing this  behavior  was  added  in
71       POSIX.1-2016.
72

ERRORS

74       EINVAL The alignment argument was not a power of two, or was not a mul‐
75              tiple of sizeof(void *).
76
77       ENOMEM There was insufficient memory to fulfill the allocation request.
78

VERSIONS

80       The functions memalign(), valloc(), and pvalloc() have  been  available
81       in all Linux libc libraries.
82
83       The function aligned_alloc() was added to glibc in version 2.16.
84
85       The function posix_memalign() is available since glibc 2.1.91.
86

ATTRIBUTES

88       For   an   explanation   of   the  terms  used  in  this  section,  see
89       attributes(7).
90
91       ┌─────────────────┬───────────────┬────────────────┐
92Interface        Attribute     Value          
93       ├─────────────────┼───────────────┼────────────────┤
94aligned_alloc(), │ Thread safety │ MT-Safe        │
95memalign(),      │               │                │
96posix_memalign() │               │                │
97       ├─────────────────┼───────────────┼────────────────┤
98valloc(),        │ Thread safety │ MT-Unsafe init │
99pvalloc()        │               │                │
100       └─────────────────┴───────────────┴────────────────┘
101

CONFORMING TO

103       The function valloc() appeared in 3.0BSD.  It is  documented  as  being
104       obsolete  in  4.3BSD,  and  as  legacy in SUSv2.  It does not appear in
105       POSIX.1.
106
107       The function pvalloc() is a GNU extension.
108
109       The function memalign() appears in SunOS 4.1.3 but not in 4.4BSD.
110
111       The function posix_memalign() comes from POSIX.1d and is  specified  in
112       POSIX.1-2001 and POSIX.1-2008.
113
114       The function aligned_alloc() is specified in the C11 standard.
115
116   Headers
117       Everybody agrees that posix_memalign() is declared in <stdlib.h>.
118
119       On  some  systems memalign() is declared in <stdlib.h> instead of <mal‐
120       loc.h>.
121
122       According to SUSv2, valloc() is declared in  <stdlib.h>.   Libc4,5  and
123       glibc declare it in <malloc.h>, and also in <stdlib.h> if suitable fea‐
124       ture test macros are defined (see above).
125

NOTES

127       On many systems there are alignment restrictions, for example, on  buf‐
128       fers  used  for  direct  block  device  I/O.  POSIX specifies the path‐
129       conf(path,_PC_REC_XFER_ALIGN) call that tells what alignment is needed.
130       Now one can use posix_memalign() to satisfy this requirement.
131
132       posix_memalign()  verifies  that  alignment  matches  the  requirements
133       detailed above.  memalign() may not check that the  alignment  argument
134       is correct.
135
136       POSIX  requires that memory obtained from posix_memalign() can be freed
137       using free(3).  Some systems provide no way to reclaim memory allocated
138       with  memalign()  or  valloc()  (because one can pass to free(3) only a
139       pointer obtained from malloc(3), while, for example,  memalign()  would
140       call malloc(3) and then align the obtained value).  The glibc implemen‐
141       tation allows memory  obtained  from  any  of  these  functions  to  be
142       reclaimed with free(3).
143
144       The  glibc malloc(3) always returns 8-byte aligned memory addresses, so
145       these functions are needed only if you require larger alignment values.
146

SEE ALSO

148       brk(2), getpagesize(2), free(3), malloc(3)
149

COLOPHON

151       This page is part of release 5.02 of the Linux  man-pages  project.   A
152       description  of  the project, information about reporting bugs, and the
153       latest    version    of    this    page,    can     be     found     at
154       https://www.kernel.org/doc/man-pages/.
155
156
157
158GNU                               2019-05-09                 POSIX_MEMALIGN(3)
Impressum