.\" 2001-10-11, 2003-08-22, aeb, added some details
.\" 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"
+.TH POSIX_MEMALIGN 3 2019-05-09 "GNU" "Linux Programmer's Manual"
.SH NAME
posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- allocate aligned memory
.SH SYNOPSIS
.nf
.B #include <stdlib.h>
-.sp
+.PP
.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
+.PP
.BI "void *memalign(size_t " alignment ", size_t " size );
.BI "void *pvalloc(size_t " size );
.fi
-.sp
+.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
-.sp
+.PP
.ad l
.BR posix_memalign ():
-_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
-.sp
+_POSIX_C_SOURCE\ >=\ 200112L
+.PP
.BR aligned_alloc ():
_ISOC11_SOURCE
-.sp
+.PP
.BR valloc ():
.br
.PD 0
.TP 4
Since glibc 2.12:
.nf
-_BSD_SOURCE ||
- (_XOPEN_SOURCE\ >=\ 500 ||
- _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
- !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
+(_XOPEN_SOURCE\ >=\ 500) && !(_POSIX_C_SOURCE\ >=\ 200112L)
+ || /* Glibc since 2.19: */ _DEFAULT_SOURCE
+ || /* Glibc versions <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
.br
.fi
.TP
Before glibc 2.12:
-_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
-_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
+_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500
+.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
.ad b
.br
(The (nonstandard) header file
The address of the allocated memory will be a multiple of
.IR "alignment" ,
which must be a power of two and a multiple of
-.IR "sizeof(void *)".
+.IR "sizeof(void\ *)" .
If
.I size
is 0, then
-.BR posix_memalign ()
-returns either NULL,
+the value placed in
+.IR "*memptr"
+is either NULL,
.\" glibc does this:
or a unique pointer value that can later be successfully passed to
.BR free (3).
-
+.PP
The obsolete function
.BR memalign ()
allocates
which must be a power of two.
.\" The behavior of memalign() for size==0 is as for posix_memalign()
.\" but no standards govern this.
-
+.PP
The function
.BR aligned_alloc ()
is the same as
.I size
should be a multiple of
.IR alignment .
-
+.PP
The obsolete function
.BR valloc ()
allocates
The memory address will be a multiple of the page size.
It is equivalent to
.IR "memalign(sysconf(_SC_PAGESIZE),size)" .
-
+.PP
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.
-
+.PP
For all of these functions, the memory is not zeroed.
.SH RETURN VALUE
.BR aligned_alloc (),
.BR valloc (),
and
.BR pvalloc ()
-return a pointer to the allocated memory, or NULL if the request fails.
-
+return a pointer to the allocated memory on success.
+On error, NULL is returned, and \fIerrno\fP is set
+to indicate the cause of the error.
+.PP
.BR posix_memalign ()
returns zero on success, or one of the error values listed in the
next section on failure.
-Note that
+The value of
.I errno
is not set.
+On Linux (and other systems),
+.BR posix_memalign ()
+does not modify
+.I memptr
+on failure.
+A requirement standardizing this behavior was added in POSIX.1-2016.
+.\" http://austingroupbugs.net/view.php?id=520
.SH ERRORS
.TP
.B EINVAL
The
.I alignment
argument was not a power of two, or was not a multiple of
-.IR "sizeof(void *)" .
+.IR "sizeof(void\ *)" .
.TP
.B ENOMEM
There was insufficient memory to fulfill the allocation request.
and
.BR pvalloc ()
have been available in all Linux libc libraries.
-
+.PP
The function
.BR aligned_alloc ()
was added to glibc in version 2.16.
-
+.PP
The function
.BR posix_memalign ()
is available since glibc 2.1.91.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR aligned_alloc (),
+.br
+.BR memalign (),
+.br
+.BR posix_memalign ()
+T} Thread safety MT-Safe
+T{
+.BR valloc (),
+.br
+.BR pvalloc ()
+T} Thread safety MT-Unsafe init
+.TE
+.sp 1
.SH CONFORMING TO
The function
.BR 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.
-
+It does not appear in POSIX.1.
+.PP
The function
.BR pvalloc ()
is a GNU extension.
-
+.PP
The function
.BR memalign ()
appears in SunOS 4.1.3 but not in 4.4BSD.
-
+.PP
The function
.BR posix_memalign ()
-comes from POSIX.1d.
-
+comes from POSIX.1d and is specified in POSIX.1-2001 and POSIX.1-2008.
+.PP
The function
.BR aligned_alloc ()
is specified in the C11 standard.
Everybody agrees that
.BR posix_memalign ()
is declared in \fI<stdlib.h>\fP.
-
+.PP
On some systems
.BR memalign ()
is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP.
-
+.PP
According to SUSv2,
.BR valloc ()
is declared in \fI<stdlib.h>\fP.
Now one can use
.BR posix_memalign ()
to satisfy this requirement.
-
+.PP
.BR posix_memalign ()
verifies that
.I alignment
may not check that the
.I alignment
argument is correct.
-
+.PP
POSIX requires that memory obtained from
.BR posix_memalign ()
can be freed using
.BR memalign ()
or
.BR valloc ()
-(because one can only pass to
+(because one can pass to
.BR free (3)
-a pointer gotten from
+only a pointer obtained from
.BR malloc (3),
while, for example,
.BR memalign ()
allows memory obtained from any of these functions to be
reclaimed with
.BR free (3).
-
+.PP
The glibc
.BR malloc (3)
-always returns 8-byte aligned memory addresses, so these functions are only
-needed if you require larger alignment values.
+always returns 8-byte aligned memory addresses, so these functions are
+needed only if you require larger alignment values.
.SH SEE ALSO
.BR brk (2),
.BR getpagesize (2),
projects / thirdparty / man-pages.git / blobdiff