posix_memalign, memalign, valloc — Allocate aligned memory
#define _XOPEN_SOURCE 600 #include <stdlib.h>
int
posix_memalign( |
void ** | memptr, |
size_t | alignment, | |
size_t | size) ; |
#include <malloc.h>
void
*valloc( |
size_t | size) ; |
void
*memalign( |
size_t | boundary, |
size_t | size) ; |
The function posix_memalign
() allocates size
bytes and places the
address of the allocated memory in *memptr
. The address of the
allocated memory will be a multiple of alignment
, which must be a
power of two and a multiple of sizeof(void *).
The obsolete function memalign
() allocates size
bytes and returns a
pointer to the allocated memory. The memory address will be a
multiple of boundary
,
which must be a power of two.
The obsolete function valloc
() allocates size
bytes and returns a
pointer to the allocated memory. The memory address will be a
multiple of the page size. It is equivalent to memalign(sysconf(_SC_PAGESIZE),size)
.
For all three routines, the memory is not zeroed.
memalign
() and valloc
() return the pointer to the
allocated memory, or NULL if the request fails.
posix_memalign
() returns
zero on success, or one of the error values listed in the
next section on failure. Note that errno
is not set.
The alignment
parameter was
not a power of two, or was not a multiple of
sizeof(void
*).
There was insufficient memory to fulfill the allocation request.
The functions memalign
() and
valloc
() have been available in
all Linux libc libraries. The function posix_memalign
() is available since glibc
2.1.91.
The function valloc
()
appeared in 3.0BSD. It is documented as being obsolete in
4.3BSD, and as legacy in SUSv2. It does not appear in
POSIX.1-2001. The function memalign
() appears in SunOS 4.1.3 but not
in 4.4BSD. The function posix_memalign
() comes from POSIX.1d.
Everybody agrees that posix_memalign
() is declared in
<stdlib.h>. In order to declare it, glibc needs
_GNU_SOURCE defined, or _XOPEN_SOURCE defined to a value
not less than 600.
On some systems memalign
()
is declared in <stdlib.h> instead of
<malloc.h>.
According to SUSv2, valloc
() is declared in <stdlib.h>.
Libc4,5 and glibc declare it in <malloc.h> and
perhaps also in <stdlib.h> (namely, if _GNU_SOURCE is
defined, or _BSD_SOURCE is defined, or, for glibc, if
_XOPEN_SOURCE_EXTENDED is defined, or, equivalently,
_XOPEN_SOURCE is defined to a value not less than 500).
On many systems there are alignment restrictions, e.g. on
buffers used for direct block device I/O. POSIX specifies the
pathconf(path,_PC_REC_XFER_ALIGN)
call that tells what alignment is needed. Now one can use
posix_memalign
() to satisfy
this requirement.
posix_memalign
() verifies
that alignment
matches the requirements detailed above. memalign
() may not check that the
boundary
parameter is
correct.
POSIX requires that memory obtained from posix_memalign
() can be freed using
free(3). Some systems
provide no way to reclaim memory allocated with memalign
() or valloc
() (because one can only pass to
free(3) a pointer gotten
from malloc(3), while e.g.
memalign
() would call malloc(3) and then align
the obtained value). GNU libc allows memory obtained from any
of these three routines to be reclaimed with free(3).
GNU libc malloc(3) always returns 8-byte aligned memory addresses, so these routines are only needed if you require larger alignment values.
brk(2), getpagesize(2), free(3), malloc(3), feature_test_macros(7)
|