memory.texi

一个C源代码分析器

@comment !!! describe mmap et al (here?)
@c !!! doc brk/sbrk

@node Memory Allocation, Character Handling, Error Reporting, Top
@chapter Memory Allocation
@cindex memory allocation
@cindex storage allocation

The GNU system provides several methods for allocating memory space
under explicit program control.  They vary in generality and in
efficiency.

@iftex
@itemize @bullet
@item
The @code{malloc} facility allows fully general dynamic allocation.
@xref{Unconstrained Allocation}.

@item
Obstacks are another facility, less general than @code{malloc} but more
efficient and convenient for stacklike allocation.  @xref{Obstacks}.

@item
The function @code{alloca} lets you allocate storage dynamically that
will be freed automatically.  @xref{Variable Size Automatic}.
@end itemize
@end iftex

@menu
* Memory Concepts::             An introduction to concepts and terminology.
* Dynamic Allocation and C::    How to get different kinds of allocation in C.
* Unconstrained Allocation::    The @code{malloc} facility allows fully general
		 		 dynamic allocation.
* Obstacks::                    Obstacks are less general than malloc
				 but more efficient and convenient.
* Variable Size Automatic::     Allocation of variable-sized blocks
				 of automatic storage that are freed when the
				 calling function returns.
* Relocating Allocator::        Waste less memory, if you can tolerate
				 automatic relocation of the blocks you get.
* Memory Warnings::		Getting warnings when memory is nearly full.
@end menu

@node Memory Concepts
@section Dynamic Memory Allocation Concepts
@cindex dynamic allocation
@cindex static allocation
@cindex automatic allocation

@dfn{Dynamic memory allocation} is a technique in which programs
determine as they are running where to store some information.  You need
dynamic allocation when the number of memory blocks you need, or how
long you continue to need them, depends on the data you are working on.

For example, you may need a block to store a line read from an input file;
since there is no limit to how long a line can be, you must allocate the
storage dynamically and make it dynamically larger as you read more of the
line.

Or, you may need a block for each record or each definition in the input
data; since you can't know in advance how many there will be, you must
allocate a new block for each record or definition as you read it.

When you use dynamic allocation, the allocation of a block of memory is an
action that the program requests explicitly.  You call a function or macro
when you want to allocate space, and specify the size with an argument.  If
you want to free the space, you do so by calling another function or macro.
You can do these things whenever you want, as often as you want.

@node Dynamic Allocation and C
@section Dynamic Allocation and C

The C language supports two kinds of memory allocation through the variables
in C programs:

@itemize @bullet
@item
@dfn{Static allocation} is what happens when you declare a static or
global variable.  Each static or global variable defines one block of
space, of a fixed size.  The space is allocated once, when your program
is started, and is never freed.

@item
@dfn{Automatic allocation} happens when you declare an automatic
variable, such as a function argument or a local variable.  The space
for an automatic variable is allocated when the compound statement
containing the declaration is entered, and is freed when that
compound statement is exited.

In GNU C, the length of the automatic storage can be an expression
that varies.  In other C implementations, it must be a constant.
@end itemize

Dynamic allocation is not supported by C variables; there is no storage
class ``dynamic'', and there can never be a C variable whose value is
stored in dynamically allocated space.  The only way to refer to
dynamically allocated space is through a pointer.  Because it is less
convenient, and because the actual process of dynamic allocation
requires more computation time, programmers use dynamic allocation only
when neither static nor automatic allocation will serve.

For example, if you want to allocate dynamically some space to hold a
@code{struct foobar}, you cannot declare a variable of type @code{struct
foobar} whose contents are the dynamically allocated space.  But you can
declare a variable of pointer type @code{struct foobar *} and assign it the
address of the space.  Then you can use the operators @samp{*} and
@samp{->} on this pointer variable to refer to the contents of the space:

@smallexample
@{
  struct foobar *ptr
     = (struct foobar *) malloc (sizeof (struct foobar));
  ptr->name = x;
  ptr->next = current_foobar;
  current_foobar = ptr;
@}
@end smallexample

@node Unconstrained Allocation
@section Unconstrained Allocation
@cindex unconstrained storage allocation
@cindex @code{malloc} function
@cindex heap, dynamic allocation from

The most general dynamic allocation facility is @code{malloc}.  It
allows you to allocate blocks of memory of any size at any time, make
them bigger or smaller at any time, and free the blocks individually at
any time (or never).

@menu
* Basic Allocation::            Simple use of @code{malloc}.
* Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
* Freeing after Malloc::        Use @code{free} to free a block you
				 got with @code{malloc}.
* Changing Block Size::         Use @code{realloc} to make a block
				 bigger or smaller.
* Allocating Cleared Space::    Use @code{calloc} to allocate a
				 block and clear it.
* Efficiency and Malloc::       Efficiency considerations in use of
				 these functions.
* Aligned Memory Blocks::       Allocating specially aligned memory:
				 @code{memalign} and @code{valloc}.
* Heap Consistency Checking::   Automatic checking for errors.
* Hooks for Malloc::            You can use these hooks for debugging
				 programs that use @code{malloc}.
* Statistics of Malloc::        Getting information about how much
				 memory your program is using.
* Summary of Malloc::           Summary of @code{malloc} and related functions.
@end menu

@node Basic Allocation
@subsection Basic Storage Allocation
@cindex allocation of memory with @code{malloc}

To allocate a block of memory, call @code{malloc}.  The prototype for
this function is in @file{stdlib.h}.
@pindex stdlib.h

@comment malloc.h stdlib.h
@comment ANSI
@deftypefun {void *} malloc (size_t @var{size})
This function returns a pointer to a newly allocated block @var{size}
bytes long, or a null pointer if the block could not be allocated.
@end deftypefun

The contents of the block are undefined; you must initialize it yourself
(or use @code{calloc} instead; @pxref{Allocating Cleared Space}).
Normally you would cast the value as a pointer to the kind of object
that you want to store in the block.  Here we show an example of doing
so, and of initializing the space with zeros using the library function
@code{memset} (@pxref{Copying and Concatenation}):

@smallexample
struct foo *ptr;
@dots{}
ptr = (struct foo *) malloc (sizeof (struct foo));
if (ptr == 0) abort ();
memset (ptr, 0, sizeof (struct foo));
@end smallexample

You can store the result of @code{malloc} into any pointer variable
without a cast, because ANSI C automatically converts the type
@code{void *} to another type of pointer when necessary.  But the cast
is necessary in contexts other than assignment operators or if you might
want your code to run in traditional C.

Remember that when allocating space for a string, the argument to
@code{malloc} must be one plus the length of the string.  This is
because a string is terminated with a null character that doesn't count
in the ``length'' of the string but does need space.  For example:

@smallexample
char *ptr;
@dots{}
ptr = (char *) malloc (length + 1);
@end smallexample

@noindent
@xref{Representation of Strings}, for more information about this.

@node Malloc Examples
@subsection Examples of @code{malloc}

If no more space is available, @code{malloc} returns a null pointer.
You should check the value of @emph{every} call to @code{malloc}.  It is
useful to write a subroutine that calls @code{malloc} and reports an
error if the value is a null pointer, returning only if the value is
nonzero.  This function is conventionally called @code{xmalloc}.  Here
it is:

@smallexample
void *
xmalloc (size_t size)
@{
  register void *value = malloc (size);
  if (value == 0)
    fatal ("virtual memory exhausted");
  return value;
@}
@end smallexample

Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
The function @code{savestring} will copy a sequence of characters into
a newly allocated null-terminated string:

@smallexample
char *
savestring (const char *ptr, size_t len)
@{
  register char *value = (char *) xmalloc (len + 1);
  memcpy (value, ptr, len);
  value[len] = '\0';
  return value;
@}
@end smallexample

The block that @code{malloc} gives you is guaranteed to be aligned so
that it can hold any type of data.  In the GNU system, the address is
always a multiple of eight; if the size of block is 16 or more, then the
address is always a multiple of 16.  Only rarely is any higher boundary
(such as a page boundary) necessary; for those cases, use
@code{memalign} or @code{valloc} (@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
call to @code{malloc}.  If you attempt to treat the block as longer than
you asked for it to be, you are liable to destroy the data that
@code{malloc} uses to keep track of its blocks, or you may destroy the
contents of another block.  If you have already allocated a block and
discover you want it to be bigger, use @code{realloc} (@pxref{Changing
Block Size}).

@node Freeing after Malloc
@subsection Freeing Memory Allocated with @code{malloc}
@cindex freeing memory allocated with @code{malloc}
@cindex heap, freeing memory from

When you no longer need a block that you got with @code{malloc}, use the
function @code{free} to make the block available to be allocated again.
The prototype for this function is in @file{stdlib.h}.
@pindex stdlib.h

@comment malloc.h stdlib.h
@comment ANSI
@deftypefun void free (void *@var{ptr})
The @code{free} function deallocates the block of storage pointed at
by @var{ptr}.
@end deftypefun

@comment stdlib.h
@comment Sun
@deftypefun void cfree (void *@var{ptr})
This function does the same thing as @code{free}.  It's provided for
backward compatibility with SunOS; you should use @code{free} instead.
@end deftypefun

Freeing a block alters the contents of the block.  @strong{Do not expect to
find any data (such as a pointer to the next block in a chain of blocks) in
the block after freeing it.}  Copy whatever you need out of the block before
freeing it!  Here is an example of the proper way to free all the blocks in
a chain, and the strings that they point to:

@smallexample
struct chain
  @{
    struct chain *next;
    char *name;
  @}

void
free_chain (struct chain *chain)
@{
  while (chain != 0)
    @{
      struct chain *next = chain->next;
      free (chain->name);
      free (chain);
      chain = next;
    @}
@}
@end smallexample

Occasionally, @code{free} can actually return memory to the operating
system and make the process smaller.  Usually, all it can do is allow a
later call to @code{malloc} to reuse the space.  In the meantime, the
space remains in your program as part of a free-list used internally by
@code{malloc}.

There is no point in freeing blocks at the end of a program, because all
of the program's space is given back to the system when the process
terminates.

@node Changing Block Size
@subsection Changing the Size of a Block
@cindex changing the size of a block (@code{malloc})

Often you do not know for certain how big a block you will ultimately need
at the time you must begin to use the block.  For example, the block might
be a buffer that you use to hold a line being read from a file; no matter
how long you make the buffer initially, you may encounter a line that is
longer.

You can make the block longer by calling @code{realloc}.  This function
is declared in @file{stdlib.h}.
@pindex stdlib.h

@comment malloc.h stdlib.h
@comment ANSI
@deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
The @code{realloc} function changes the size of the block whose address is
@var{ptr} to be @var{newsize}.

Since the space after the end of the block may be in use, @code{realloc}
may find it necessary to copy the block to a new address where more free
space is available.  The value of @code{realloc} is the new address of the
block.  If the block needs to be moved, @code{realloc} copies the old
contents.

If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
like @samp{malloc (@var{newsize})}.  This can be convenient, but beware
that older implementations (before ANSI C) may not support this
behavior, and will probably crash when @code{realloc} is passed a null
pointer.
@end deftypefun

Like @code{malloc}, @code{realloc} may return a null pointer if no