mirror/glibc
2
0
Fork 0
mirror of git://sourceware.org/git/glibc.git synced 2024-11-21 01:12:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

manual/memory.texi: Bring aligned allocation docs up to date.

Browse Source 
The current documentation suggests using memalign and valloc which
are now considered obsolete, so suggest using posix_memalign instead.
Also document the possible error return and errno values for memalign
and posix_memalign and improve documentation of __memalign_hook.

ChangeLog:

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.
	(Aligned Memory Blocks): Remove suggestion to use memalign
	or valloc.  Remove obsolete comment about BSD.
	Document memalign errno values and mark the function obsolete.
	Document posix_memalign returned error codes.  Mark valloc
	as obsolete.  (Hooks for Malloc): __memalign_hook is also
	called for posix_memalign and valloc.
	(Summary of Malloc): Add posix_memalign to function summary.
	__memalign_hook is also called for posix_memalign and valloc.
This commit is contained in:
Will Newton 2013-11-06 09:48:10 +00:00
parent 8d561986c0
commit 0a096e4487
2 changed files with 58 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
ChangeLog
View File

@ -1,3 +1,17 @@
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.
(Aligned Memory Blocks): Remove suggestion to use memalign
or valloc. Remove obsolete comment about BSD.
Document memalign errno values and mark the function obsolete.
Document posix_memalign returned error codes. Mark valloc
as obsolete. (Hooks for Malloc): __memalign_hook is also
called for posix_memalign and valloc.
(Summary of Malloc): Add posix_memalign to function summary.
__memalign_hook is also called for posix_memalign and valloc.
2013-12-16 Siddhesh Poyarekar <siddhesh@redhat.com>
* sysdeps/ieee754/dbl-64/s_sin.c (TAYLOR_SINCOS): Rename to

61
manual/memory.texi
View File

@ -380,10 +380,10 @@ savestring (const char *ptr, size_t len)
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 most systems, and a multiple of 16 on
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{memalign},
@code{posix_memalign} or @code{valloc} (@pxref{Aligned Memory Blocks}).
boundary) necessary; for those cases, use @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,14 +616,8 @@ 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{memalign}, @code{posix_memalign}, or
@code{valloc}. @code{memalign} is declared in @file{malloc.h} and
@code{posix_memalign} is declared in @file{stdlib.h}.
With @theglibc{}, you can use @code{free} to free the blocks that
@code{memalign}, @code{posix_memalign}, and @code{valloc} return. That
does not work in BSD, however---BSD does not provide any way to free
such blocks.
power of two than that, use @code{posix_memalign}. @code{posix_memalign}
is declared in @file{stdlib.h}.
@comment malloc.h
@comment BSD
@ -633,6 +627,21 @@ address is a multiple of @var{boundary}. The @var{boundary} must be a
power of two! The function @code{memalign} works by allocating a
somewhat larger block, and then returning an address within the block
that is on the specified boundary.
The @code{memalign} 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.
@end table
The @code{memalign} function is obsolete and @code{posix_memalign} should
be used instead.
@end deftypefun
@comment stdlib.h
@ -647,6 +656,16 @@ parameter @var{alignment}: the value must be a power of two multiple of
If the function succeeds in allocation memory a pointer to the allocated
memory is returned in @code{*@var{memptr}} and the return value is zero.
Otherwise the function returns an error value indicating the problem.
The possible error values returned are:
@table @code
@item ENOMEM
There was insufficient memory available to satisfy the request.
@item EINVAL
@var{alignment} is not a power of two multiple of @code{sizeof (void *)}.
@end table
This function was introduced in POSIX 1003.1d.
@end deftypefun
@ -667,6 +686,9 @@ 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.
@end deftypefun
@node Malloc Tunable Parameters
@ -902,17 +924,17 @@ 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}
uses whenever it is 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{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:
@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} function was called. This value allows you to trace the
memory consumption of the program.
the @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
@ -1118,6 +1140,10 @@ Space}.
Allocate a block of @var{size} bytes, starting on a page boundary.
@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}.
@item void *memalign (size_t @var{size}, size_t @var{boundary})
Allocate a block of @var{size} bytes, starting on an address that is a
multiple of @var{boundary}. @xref{Aligned Memory Blocks}.
@ -1140,7 +1166,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} uses whenever it is called.
A pointer to a function that @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.