memory.texi

一个C源代码分析器

memory space is available to make the block bigger.  When this happens,
the original block is untouched; it has not been modified or relocated.

In most cases it makes no difference what happens to the original block
when @code{realloc} fails, because the application program cannot continue
when it is out of memory, and the only thing to do is to give a fatal error
message.  Often it is convenient to write and use a subroutine,
conventionally called @code{xrealloc}, that takes care of the error message
as @code{xmalloc} does for @code{malloc}:

@smallexample
void *
xrealloc (void *ptr, size_t size)
@{
  register void *value = realloc (ptr, size);
  if (value == 0)
    fatal ("Virtual memory exhausted");
  return value;
@}
@end smallexample

You can also use @code{realloc} to make a block smaller.  The reason you
would do this is to avoid tying up a lot of memory space when only a little
is needed.  Making a block smaller sometimes necessitates copying it, so it
can fail if no other space is available.

If the new size you specify is the same as the old size, @code{realloc}
is guaranteed to change nothing and return the same address that you gave.

@node Allocating Cleared Space
@subsection Allocating Cleared Space

The function @code{calloc} allocates memory and clears it to zero.  It
is declared in @file{stdlib.h}.
@pindex stdlib.h

@comment malloc.h stdlib.h
@comment ANSI
@deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
This function allocates a block long enough to contain a vector of
@var{count} elements, each of size @var{eltsize}.  Its contents are
cleared to zero before @code{calloc} returns.
@end deftypefun

You could define @code{calloc} as follows:

@smallexample
void *
calloc (size_t count, size_t eltsize)
@{
  size_t size = count * eltsize;
  void *value = malloc (size);
  if (value != 0)
    memset (value, 0, size);
  return value;
@}
@end smallexample

We rarely use @code{calloc} today, because it is equivalent to such a
simple combination of other features that are more often used.  It is a
historical holdover that is not quite obsolete.

@node Efficiency and Malloc
@subsection Efficiency Considerations for @code{malloc}
@cindex efficiency and @code{malloc}

To make the best use of @code{malloc}, it helps to know that the GNU
version of @code{malloc} always dispenses small amounts of memory in
blocks whose sizes are powers of two.  It keeps separate pools for each
power of two.  This holds for sizes up to a page size.  Therefore, if
you are free to choose the size of a small block in order to make
@code{malloc} more efficient, make it a power of two.
@c !!! xref getpagesize

Once a page is split up for a particular block size, it can't be reused
for another size unless all the blocks in it are freed.  In many
programs, this is unlikely to happen.  Thus, you can sometimes make a
program use memory more efficiently by using blocks of the same size for
many different purposes.

When you ask for memory blocks of a page or larger, @code{malloc} uses a
different strategy; it rounds the size up to a multiple of a page, and
it can coalesce and split blocks as needed.

The reason for the two strategies is that it is important to allocate
and free small blocks as fast as possible, but speed is less important
for a large block since the program normally spends a fair amount of
time using it.  Also, large blocks are normally fewer in number.
Therefore, for large blocks, it makes sense to use a method which takes
more time to minimize the wasted space.

@node Aligned Memory Blocks
@subsection Allocating Aligned Memory Blocks

@cindex page boundary
@cindex alignment (with @code{malloc})
@pindex stdlib.h
The address of a block returned by @code{malloc} or @code{realloc} in
the GNU system is always a multiple of eight.  If you need a block whose
address is a multiple of a higher power of two than that, use
@code{memalign} or @code{valloc}.  These functions are declared in
@file{stdlib.h}.

With the GNU library, you can use @code{free} to free the blocks that
@code{memalign} and @code{valloc} return.  That does not work in BSD,
however---BSD does not provide any way to free such blocks.

@comment malloc.h stdlib.h
@comment BSD
@deftypefun {void *} memalign (size_t @var{size}, size_t @var{boundary})
The @code{memalign} function allocates a block of @var{size} bytes whose
address is a multiple of @var{boundary}.  The @var{boundary} must be a
power of two!  The function @code{memalign} works by calling
@code{malloc} to allocate a somewhat larger block, and then returning an
address within the block that is on the specified boundary.
@end deftypefun

@comment malloc.h stdlib.h
@comment BSD
@deftypefun {void *} valloc (size_t @var{size})
Using @code{valloc} is like using @code{memalign} and passing the page size
as the value of the second argument.  It is implemented like this:

@smallexample
void *
valloc (size_t size)
@{
  return memalign (size, getpagesize ());
@}
@end smallexample
@c !!! xref getpagesize
@end deftypefun

@node Heap Consistency Checking
@subsection Heap Consistency Checking

@cindex heap consistency checking
@cindex consistency checking, of heap

You can ask @code{malloc} to check the consistency of dynamic storage by
using the @code{mcheck} function.  This function is a GNU extension,
declared in @file{malloc.h}.
@pindex malloc.h

@comment malloc.h
@comment GNU
@deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status}))
Calling @code{mcheck} tells @code{malloc} to perform occasional
consistency checks.  These will catch things such as writing
past the end of a block that was allocated with @code{malloc}.

The @var{abortfn} argument is the function to call when an inconsistency
is found.  If you supply a null pointer, then @code{mcheck} uses a
default function which prints a message and calls @code{abort}
(@pxref{Aborting a Program}).  The function you supply is called with
one argument, which says what sort of inconsistency was detected; its
type is described below.

It is too late to begin allocation checking once you have allocated
anything with @code{malloc}.  So @code{mcheck} does nothing in that
case.  The function returns @code{-1} if you call it too late, and
@code{0} otherwise (when it is successful).

The easiest way to arrange to call @code{mcheck} early enough is to use
the option @samp{-lmcheck} when you link your program; then you don't
need to modify your program source at all.
@end deftypefun

@deftypefun {enum mcheck_status} mprobe (void *@var{pointer})
The @code{mprobe} function lets you explicitly check for inconsistencies
in a particular allocated block.  You must have already called
@code{mcheck} at the beginning of the program, to do its occasional
checks; calling @code{mprobe} requests an additional consistency check
to be done at the time of the call.

The argument @var{pointer} must be a pointer returned by @code{malloc}
or @code{realloc}.  @code{mprobe} returns a value that says what
inconsistency, if any, was found.  The values are described below.
@end deftypefun

@deftp {Data Type} {enum mcheck_status}
This enumerated type describes what kind of inconsistency was detected
in an allocated block, if any.  Here are the possible values:

@table @code
@item MCHECK_DISABLED
@code{mcheck} was not called before the first allocation.
No consistency checking can be done.
@item MCHECK_OK
No inconsistency detected.
@item MCHECK_HEAD
The data immediately before the block was modified.
This commonly happens when an array index or pointer
is decremented too far.
@item MCHECK_TAIL
The data immediately after the block was modified.
This commonly happens when an array index or pointer
is incremented too far.
@item MCHECK_FREE
The block was already freed.
@end table
@end deftp

@node Hooks for Malloc
@subsection Storage Allocation Hooks
@cindex allocation hooks, for @code{malloc}

The GNU C library lets you modify the behavior of @code{malloc},
@code{realloc}, and @code{free} by specifying appropriate hook
functions.  You can use these hooks to help you debug programs that use
dynamic storage allocation, for example.

The hook variables are declared in @file{malloc.h}.
@pindex malloc.h

@comment malloc.h
@comment GNU
@defvar __malloc_hook
The value of this variable is a pointer to function that @code{malloc}
uses whenever it is called.  You should define this function to look
like @code{malloc}; that is, like:

@smallexample
void *@var{function} (size_t @var{size})
@end smallexample
@end defvar

@comment malloc.h
@comment GNU
@defvar __realloc_hook
The value of this variable is a pointer to function that @code{realloc}
uses whenever it is called.  You should define this function to look
like @code{realloc}; that is, like:

@smallexample
void *@var{function} (void *@var{ptr}, size_t @var{size})
@end smallexample
@end defvar

@comment malloc.h
@comment GNU
@defvar __free_hook
The value of this variable is a pointer to function that @code{free}
uses whenever it is called.  You should define this function to look
like @code{free}; that is, like:

@smallexample
void @var{function} (void *@var{ptr})
@end smallexample
@end defvar

You must make sure that the function you install as a hook for one of
these functions does not call that function recursively without restoring
the old value of the hook first!  Otherwise, your program will get stuck
in an infinite recursion.

Here is an example showing how to use @code{__malloc_hook} properly.  It
installs a function that prints out information every time @code{malloc}
is called.

@smallexample
static void *(*old_malloc_hook) (size_t);
static void *
my_malloc_hook (size_t size)
@{
  void *result;
  __malloc_hook = old_malloc_hook;
  result = malloc (size);
  __malloc_hook = my_malloc_hook;
  printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
  return result;
@}

main ()
@{
  ...
  old_malloc_hook = __malloc_hook;
  __malloc_hook = my_malloc_hook;
  ...
@}
@end smallexample

The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
installing such hooks.

@c __morecore, __after_morecore_hook are undocumented
@c It's not clear whether to document them.

@node Statistics of Malloc
@subsection Statistics for Storage Allocation with @code{malloc}

@cindex allocation statistics
You can get information about dynamic storage allocation by calling the
@code{mstats} function.  This function and its associated data type are
declared in @file{malloc.h}; they are a GNU extension.
@pindex malloc.h

@comment malloc.h
@comment GNU
@deftp {Data Type} {struct mstats}
This structure type is used to return information about the dynamic
storage allocator.  It contains the following members:

@table @code
@item size_t bytes_total
This is the total size of memory managed by @code{malloc}, in bytes.

@item size_t chunks_used
This is the number of chunks in use.  (The storage allocator internally
gets chunks of memory from the operating system, and then carves them up
to satisfy individual @code{malloc} requests; see @ref{Efficiency and
Malloc}.)

@item size_t bytes_used
This is the number of bytes in use.

@item size_t chunks_free
This is the number of chunks which are free -- that is, that have been
allocated by the operating system to your program, but which are not
now being used.

@item size_t bytes_free
This is the number of bytes which are free.
@end table
@end deftp

@comment malloc.h
@comment GNU
@deftypefun {struct mstats} mstats (void)
This function returns information about the current dynamic memory usage
in a structure of type @code{struct mstats}.
@end deftypefun

@node Summary of Malloc
@subsection Summary of @code{malloc}-Related Functions

Here is a summary of the functions that work with @code{malloc}:

@table @code
@item void *malloc (size_t @var{size})
Allocate a block of @var{size} bytes.  @xref{Basic Allocation}.

@item void free (void *@var{addr})
Free a block previously allocated by @code{malloc}.  @xref{Freeing after
Malloc}.