.\" License.
.\"
.\" 2001-10-11, 2003-08-22, aeb, added some details
-.TH POSIX_MEMALIGN 3 2010-09-20 "GNU" "Linux Programmer's Manual"
+.\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com>
+.\" Document pvalloc() and aligned_alloc()
+.TH POSIX_MEMALIGN 3 2012-03-23 "GNU" "Linux Programmer's Manual"
.SH NAME
-posix_memalign, memalign, valloc \- Allocate aligned memory
+posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- Allocate aligned memory
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
.sp
.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
+.BI "void *aligned_alloc(size_t " alignment ", size_t " size );
+.BI "void *valloc(size_t " size );
.sp
.B #include <malloc.h>
.sp
-.BI "void *valloc(size_t " size );
-.BI "void *memalign(size_t " boundary ", size_t " size );
+.BI "void *memalign(size_t " alignment ", size_t " size );
+.BI "void *pvalloc(size_t " size );
.fi
.sp
.in -4n
.BR posix_memalign ():
_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
.sp
+.BR aligned_alloc ():
+_ISOC11_SOURCE
+.sp
.BR valloc ():
.br
.PD 0
Before glibc 2.12:
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+.ad b
+.br
+(The (nonstandard) header file
+.I <malloc.h>
+also exposes the declaration of
+.BR valloc ();
+no feature test macros are required.)
.RE
.PD
-.ad b
.SH DESCRIPTION
The function
.BR posix_memalign ()
.I size
bytes and returns a pointer to the allocated memory.
The memory address will be a multiple of
-.IR "boundary" ,
+.IR alignment ,
which must be a power of two.
.\" The behavior of memalign() for size==0 is as for posix_memalign()
.\" but no standards govern this.
+The function
+.BR aligned_alloc ()
+is the same as
+.BR memalign (),
+except for the added restriction that
+.I size
+should be a multiple of
+.IR alignment .
+
+
The obsolete function
.BR valloc ()
allocates
It is equivalent to
.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
-For all three routines, the memory is not zeroed.
+The obsolete function
+.BR pvalloc ()
+is similar to
+.BR valloc (),
+but rounds the size of the allocation up to
+the next multiple of the system page size.
+
+For all of these functions, the memory is not zeroed.
.SH "RETURN VALUE"
-.BR memalign ()
+.BR aligned_alloc (),
+.BR memalign (),
+.BR valloc (),
and
-.BR valloc ()
-return the pointer to the allocated memory, or NULL if the request fails.
+.BR pvalloc ()
+return a pointer to the allocated memory, or NULL if the request fails.
.BR posix_memalign ()
returns zero on success, or one of the error values listed in the
There was insufficient memory to fulfill the allocation request.
.SH VERSIONS
The functions
-.BR memalign ()
+.BR memalign (),
+.BR valloc (),
and
-.BR valloc ()
+.BR pvalloc ()
have been available in all Linux libc libraries.
+
+The function
+.BR aligned_alloc ()
+was added to glibc in version 2.16.
+
The function
.BR posix_memalign ()
is available since glibc 2.1.91.
It is documented as being obsolete in 4.3BSD,
and as legacy in SUSv2.
It does not appear in POSIX.1-2001.
+
+The function
+.BR pvalloc ()
+is a GNU extension.
+
The function
.BR memalign ()
appears in SunOS 4.1.3 but not in 4.4BSD.
+
The function
.BR posix_memalign ()
comes from POSIX.1d.
+
+The function
+.I aligned_alloc ()
+is specified in the C11 standard.
+.\"
.SS Headers
Everybody agrees that
.BR posix_memalign ()
According to SUSv2,
.BR valloc ()
is declared in \fI<stdlib.h>\fP.
-Libc4,5 and glibc declare it in \fI<malloc.h>\fP and perhaps also in
+Libc4,5 and glibc declare it in \fI<malloc.h>\fP, and also in
\fI<stdlib.h>\fP
-(namely, if
-.B _GNU_SOURCE
-is defined, or
-.B _BSD_SOURCE
-is defined, or,
-for glibc, if
-.B _XOPEN_SOURCE_EXTENDED
-is defined, or, equivalently,
-.B _XOPEN_SOURCE
-is defined to a value not less than 500).
+if suitable feature test macros are defined (see above).
.SH NOTES
On many systems there are alignment restrictions, for example, on buffers
used for direct block device I/O.
matches the requirements detailed above.
.BR memalign ()
may not check that the
-.I boundary
+.I alignment
argument is correct.
POSIX requires that memory obtained from
.\" but not to
.\" .IR realloc (3).
The glibc implementation
-allows memory obtained from any of these three routines to be
+allows memory obtained from any of these these functions to be
reclaimed with
.BR free (3).
The glibc
.BR malloc (3)
-always returns 8-byte aligned memory addresses, so these routines are only
+always returns 8-byte aligned memory addresses, so these functions are only
needed if you require larger alignment values.
.SH "SEE ALSO"
.BR brk (2),
OSDN Git Service
