diff options
| -rw-r--r-- | ChangeLog | 10 | ||||
| -rw-r--r-- | manual/memory.texi | 63 |
2 files changed, 57 insertions, 16 deletions
@@ -1,5 +1,15 @@ 2013-12-16 Will Newton <will.newton@linaro.org> + * manual/memory.texi (Malloc Examples): Mention aligned_alloc. + (Aligned Memory Blocks): Add documentation for aligned_alloc + and suggest it as an alternative to posix_memalign. + (Hooks for Malloc): Document __memalign_hook is also called + for aligned_alloc. (Summary of Malloc): Add summary for + aligned alloc. Document __memalign_hook is also called + for aligned_alloc. + +2013-12-16 Will Newton <will.newton@linaro.org> + * manual/memory.texi (Malloc Examples): Clarify default alignment documentation. Suggest posix_memalign rather than memalign or valloc. diff --git a/manual/memory.texi b/manual/memory.texi index 3d96f353be..55a6a50ae6 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -382,8 +382,8 @@ The block that @code{malloc} gives you is guaranteed to be aligned so that it can hold any type of data. On @gnusystems{}, the address is always a multiple of eight on 32-bit systems, and a multiple of 16 on 64-bit systems. Only rarely is any higher boundary (such as a page -boundary) necessary; for those cases, use @code{posix_memalign} -(@pxref{Aligned Memory Blocks}). +boundary) necessary; for those cases, use @code{aligned_alloc} or +@code{posix_memalign} (@pxref{Aligned Memory Blocks}). Note that the memory located after the end of the block is likely to be in use for something else; perhaps a block already allocated by another @@ -616,8 +616,31 @@ after calling @code{free} wastes memory. The size threshold for The address of a block returned by @code{malloc} or @code{realloc} in @gnusystems{} is always a multiple of eight (or sixteen on 64-bit systems). If you need a block whose address is a multiple of a higher -power of two than that, use @code{posix_memalign}. @code{posix_memalign} -is declared in @file{stdlib.h}. +power of two than that, use @code{aligned_alloc} or @code{posix_memalign}. +@code{aligned_alloc} and @code{posix_memalign} are declared in +@file{stdlib.h}. + +@comment stdlib.h +@deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size}) +The @code{aligned_alloc} function allocates a block of @var{size} bytes whose +address is a multiple of @var{alignment}. The @var{alignment} must be a +power of two and @var{size} must be a multiple of @var{alignment}. + +The @code{aligned_alloc} function returns a null pointer on error and sets +@code{errno} to one of the following values: + +@table @code +@item ENOMEM +There was insufficient memory available to satisfy the request. + +@item EINVAL +@var{alignment} is not a power of two. + +This function was introduced in @w{ISO C11} and hence may have better +portability to modern non-POSIX systems than @code{posix_memalign}. +@end table + +@end deftypefun @comment malloc.h @comment BSD @@ -640,8 +663,8 @@ There was insufficient memory available to satisfy the request. @end table -The @code{memalign} function is obsolete and @code{posix_memalign} should -be used instead. +The @code{memalign} function is obsolete and @code{aligned_alloc} or +@code{posix_memalign} should be used instead. @end deftypefun @comment stdlib.h @@ -667,7 +690,9 @@ There was insufficient memory available to satisfy the request. @end table -This function was introduced in POSIX 1003.1d. +This function was introduced in POSIX 1003.1d. Although this function is +superseded by @code{aligned_alloc}, it is more portable to older POSIX +systems that do not support @w{ISO C11}. @end deftypefun @comment malloc.h stdlib.h @@ -687,8 +712,8 @@ valloc (size_t size) @ref{Query Memory Parameters} for more information about the memory subsystem. -The @code{valloc} function is obsolete and @code{posix_memalign} should -be used instead. +The @code{valloc} function is obsolete and @code{aligned_alloc} or +@code{posix_memalign} should be used instead. @end deftypefun @node Malloc Tunable Parameters @@ -924,17 +949,19 @@ memory consumption of the program. @comment malloc.h @comment GNU @defvar __memalign_hook -The value of this variable is a pointer to function that @code{memalign}, -@code{posix_memalign} and @code{valloc} use whenever they are called. -You should define this function to look like @code{memalign}; that is, like: +The value of this variable is a pointer to function that @code{aligned_alloc}, +@code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they +are called. You should define this function to look like @code{aligned_alloc}; +that is, like: @smallexample void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller}) @end smallexample The value of @var{caller} is the return address found on the stack when -the @code{memalign}, @code{posix_memalign} or @code{valloc} functions are -called. This value allows you to trace the memory consumption of the program. +the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or +@code{valloc} functions are called. This value allows you to trace the +memory consumption of the program. @end defvar You must make sure that the function you install as a hook for one of @@ -1140,6 +1167,10 @@ Space}. Allocate a block of @var{size} bytes, starting on a page boundary. @xref{Aligned Memory Blocks}. +@item void *aligned_alloc (size_t @var{size}, size_t @var{alignment}) +Allocate a block of @var{size} bytes, starting on an address that is a +multiple of @var{alignment}. @xref{Aligned Memory Blocks}. + @item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size}) Allocate a block of @var{size} bytes, starting on an address that is a multiple of @var{alignment}. @xref{Aligned Memory Blocks}. @@ -1166,8 +1197,8 @@ A pointer to a function that @code{realloc} uses whenever it is called. A pointer to a function that @code{free} uses whenever it is called. @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller}) -A pointer to a function that @code{memalign}, @code{posix_memalign} and -@code{valloc} use whenever they are called. +A pointer to a function that @code{aligned_alloc}, @code{memalign}, +@code{posix_memalign} and @code{valloc} use whenever they are called. @item struct mallinfo mallinfo (void) Return information about the current dynamic memory usage. |