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():
24           _POSIX_C_SOURCE >= 200112L
25
26       aligned_alloc():
27           _ISOC11_SOURCE
28
29       valloc():
30           Since glibc 2.12:
31               (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
32                   || /* Glibc since 2.19: */ _DEFAULT_SOURCE
33                   || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
34           Before glibc 2.12:
35               _BSD_SOURCE || _XOPEN_SOURCE >= 500
36

DESCRIPTION

38       The function posix_memalign() allocates size bytes and places  the  ad‐
39       dress of the allocated memory in *memptr.  The address of the allocated
40       memory will be a multiple of alignment, which must be a  power  of  two
41       and  a  multiple of sizeof(void *).  This address can later be success‐
42       fully passed to free(3).  If size  is  0,  then  the  value  placed  in
43       *memptr is either NULL or a unique pointer value.
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 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-2008 TC2.
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       since at least glibc 2.0.
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  at‐
89       tributes(7).
90
91       ┌─────────────────────────────────────┬───────────────┬────────────────┐
92Interface                            Attribute     Value          
93       ├─────────────────────────────────────┼───────────────┼────────────────┤
94aligned_alloc(), memalign(),         │ Thread safety │ MT-Safe        │
95posix_memalign()                     │               │                │
96       ├─────────────────────────────────────┼───────────────┼────────────────┤
97valloc(), pvalloc()                  │ Thread safety │ MT-Unsafe init │
98       └─────────────────────────────────────┴───────────────┴────────────────┘
99

CONFORMING TO

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

NOTES

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

SEE ALSO

146       brk(2), getpagesize(2), free(3), malloc(3)
147

COLOPHON

149       This page is part of release 5.13 of the Linux  man-pages  project.   A
150       description  of  the project, information about reporting bugs, and the
151       latest    version    of    this    page,    can     be     found     at
152       https://www.kernel.org/doc/man-pages/.
153
154
155
156GNU                               2021-03-22                 POSIX_MEMALIGN(3)
Impressum