2276 lines
84 KiB
Plaintext
2276 lines
84 KiB
Plaintext
@comment !!! describe mmap et al (here?)
|
|
@c !!! doc brk/sbrk
|
|
|
|
@node Memory Allocation, Character Handling, Error Reporting, Top
|
|
@chapter Memory Allocation
|
|
@c %MENU% Allocating memory dynamically and manipulating it via pointers
|
|
@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.
|
|
* Allocation Debugging:: Finding memory leaks and not freed memory.
|
|
* 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.
|
|
@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 generally 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}.
|
|
* Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation
|
|
parameters.
|
|
* 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 ISO
|
|
@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 @w{ISO 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
|
|
@group
|
|
char *
|
|
savestring (const char *ptr, size_t len)
|
|
@{
|
|
register char *value = (char *) xmalloc (len + 1);
|
|
value[len] = '\0';
|
|
return (char *) memcpy (value, ptr, len);
|
|
@}
|
|
@end group
|
|
@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 on most 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} 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 ISO
|
|
@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 ISO
|
|
@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 @w{ISO 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
|
|
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.
|
|
@comment The following is no longer true with the new malloc.
|
|
@comment But it seems wise to keep the warning for other implementations.
|
|
In several allocation implementations, 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 ISO
|
|
@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
|
|
|
|
But in general, it is not guaranteed that @code{calloc} calls
|
|
@code{malloc} internally. Therefore, if an application provides its own
|
|
@code{malloc}/@code{realloc}/@code{free} outside the C library, it
|
|
should always define @code{calloc}, too.
|
|
|
|
@node Efficiency and Malloc
|
|
@subsection Efficiency Considerations for @code{malloc}
|
|
@cindex efficiency and @code{malloc}
|
|
|
|
@ignore
|
|
|
|
@c No longer true, see below instead.
|
|
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.
|
|
|
|
@end ignore
|
|
|
|
As opposed to other versions, the @code{malloc} in GNU libc does not
|
|
round up block sizes to powers of two, neither for large nor for small
|
|
sizes. Neighboring chunks can be coalesced on a @code{free} no matter
|
|
what their size is. This makes the implementation suitable for all
|
|
kinds of allocation patterns without generally incurring high memory
|
|
waste through fragmentation.
|
|
|
|
Very large blocks (much larger than a page) are allocated with
|
|
@code{mmap} (anonymous or via @code{/dev/zero}) by this implementation.
|
|
This has the great advantage that these chunks are returned to the
|
|
system immediately when they are freed. Therefore, it cannot happen
|
|
that a large chunk becomes ``locked'' in between smaller ones and even
|
|
after calling @code{free} wastes memory. The size threshold for
|
|
@code{mmap} to be used can be adjusted with @code{mallopt}. The use of
|
|
@code{mmap} can also be disabled completely.
|
|
|
|
@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 (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} 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{boundary}, size_t @var{size})
|
|
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 allocating 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 (getpagesize (), size);
|
|
@}
|
|
@end smallexample
|
|
@c !!! xref getpagesize
|
|
@end deftypefun
|
|
|
|
@node Malloc Tunable Parameters
|
|
@subsection Malloc Tunable Parameters
|
|
|
|
You can adjust some parameters for dynamic memory allocation with the
|
|
@code{mallopt} function. This function is the general SVID/XPG
|
|
interface, defined in @file{malloc.h}.
|
|
@pindex malloc.h
|
|
|
|
@deftypefun int mallopt (int @var{param}, int @var{value})
|
|
When calling @code{mallopt}, the @var{param} argument specifies the
|
|
parameter to be set, and @var{value} the new value to be set. Possible
|
|
choices for @var{param}, as defined in @file{malloc.h}, are:
|
|
|
|
@table @code
|
|
@item M_TRIM_THRESHOLD
|
|
This is the minimum size (in bytes) of the top-most, releasable chunk
|
|
that will cause @code{sbrk} to be called with a negative argument in
|
|
order to return memory to the system.
|
|
@item M_TOP_PAD
|
|
This parameter determines the amount of extra memory to obtain from the
|
|
system when a call to @code{sbrk} is required. It also specifies the
|
|
number of bytes to retain when shrinking the heap by calling @code{sbrk}
|
|
with a negative argument. This provides the necessary hysteresis in
|
|
heap size such that excessive amounts of system calls can be avoided.
|
|
@item M_MMAP_THRESHOLD
|
|
All chunks larger than this value are allocated outside the normal
|
|
heap, using the @code{mmap} system call. This way it is guaranteed
|
|
that the memory for these chunks can be returned to the system on
|
|
@code{free}.
|
|
@item M_MMAP_MAX
|
|
The maximum number of chunks to allocate with @code{mmap}. Setting this
|
|
to zero disables all use of @code{mmap}.
|
|
@end table
|
|
|
|
@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{mcheck.h}.
|
|
@pindex mcheck.h
|
|
|
|
@comment mcheck.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. Alternatively you might use
|
|
a debugger to insert a call to @code{mcheck} whenever the program is
|
|
started, for example these gdb commands will automatically call @code{mcheck}
|
|
whenever the program starts:
|
|
|
|
@smallexample
|
|
(gdb) break main
|
|
Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
|
|
(gdb) command 1
|
|
Type commands for when breakpoint 1 is hit, one per line.
|
|
End with a line saying just "end".
|
|
>call mcheck(0)
|
|
>continue
|
|
>end
|
|
(gdb) ...
|
|
@end smallexample
|
|
|
|
This will however only work if no initialization function of any object
|
|
involved calls any of the @code{malloc} functions since @code{mcheck}
|
|
must be called before the first such function.
|
|
|
|
@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
|
|
|
|
Another possibility to check for and guard against bugs in the use of
|
|
@code{malloc}, @code{realloc} and @code{free} is to set the environment
|
|
variable @code{MALLOC_CHECK_}. When @code{MALLOC_CHECK_} is set, a
|
|
special (less efficient) implementation is used which is designed to be
|
|
tolerant against simple errors, such as double calls of @code{free} with
|
|
the same argument, or overruns of a single byte (off-by-one bugs). Not
|
|
all such errors can be protected against, however, and memory leaks can
|
|
result. If @code{MALLOC_CHECK_} is set to @code{0}, any detected heap
|
|
corruption is silently ignored; if set to @code{1}, a diagnostic is
|
|
printed on @code{stderr}; if set to @code{2}, @code{abort} is called
|
|
immediately. This can be useful because otherwise a crash may happen
|
|
much later, and the true cause for the problem is then very hard to
|
|
track down.
|
|
|
|
So, what's the difference between using @code{MALLOC_CHECK_} and linking
|
|
with @samp{-lmcheck}? @code{MALLOC_CHECK_} is orthogonal with respect to
|
|
@samp{-lmcheck}. @samp{-lmcheck} has been added for backward
|
|
compatibility. Both @code{MALLOC_CHECK_} and @samp{-lmcheck} should
|
|
uncover the same bugs - but using @code{MALLOC_CHECK_} you don't need to
|
|
recompile your application.
|
|
|
|
@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 the 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}, void *@var{caller})
|
|
@end smallexample
|
|
|
|
The value of @var{caller} is the return address found on the stack when
|
|
the @code{malloc} function was called. This value allows you to trace
|
|
the memory consumption of the program.
|
|
@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}, void *@var{caller})
|
|
@end smallexample
|
|
|
|
The value of @var{caller} is the return address found on the stack when
|
|
the @code{realloc} function was called. This value allows you to trace the
|
|
memory consumption of the program.
|
|
@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}, void *@var{caller})
|
|
@end smallexample
|
|
|
|
The value of @var{caller} is the return address found on the stack when
|
|
the @code{free} function was called. This value allows you to trace the
|
|
memory consumption of the program.
|
|
@end defvar
|
|
|
|
@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:
|
|
|
|
@smallexample
|
|
void *@var{function} (size_t @var{size}, size_t @var{alignment})
|
|
@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. Before calling the function recursively, one
|
|
should make sure to restore all the hooks to their previous value. When
|
|
coming back from the recursive call, all the hooks should be resaved
|
|
since a hook might modify itself.
|
|
|
|
@comment malloc.h
|
|
@comment GNU
|
|
@defvar __malloc_initialize_hook
|
|
The value of this variable is a pointer to a function that is called
|
|
once when the malloc implementation is initialized. This is a weak
|
|
variable, so it can be overridden in the application with a definition
|
|
like the following:
|
|
|
|
@smallexample
|
|
void (*@var{__malloc_initialize_hook}) (void) = my_init_hook;
|
|
@end smallexample
|
|
@end defvar
|
|
|
|
An issue to look out for is the time at which the malloc hook functions
|
|
can be safely installed. If the hook functions call the malloc-related
|
|
functions recursively, it is necessary that malloc has already properly
|
|
initialized itself at the time when @code{__malloc_hook} etc. is
|
|
assigned to. On the other hand, if the hook functions provide a
|
|
complete malloc implementation of their own, it is vital that the hooks
|
|
are assigned to @emph{before} the very first @code{malloc} call has
|
|
completed, because otherwise a chunk obtained from the ordinary,
|
|
un-hooked malloc may later be handed to @code{__free_hook}, for example.
|
|
|
|
In both cases, the problem can be solved by setting up the hooks from
|
|
within a user-defined function pointed to by
|
|
@code{__malloc_initialize_hook}---then the hooks will be set up safely
|
|
at the right time.
|
|
|
|
Here is an example showing how to use @code{__malloc_hook} and
|
|
@code{__free_hook} properly. It installs a function that prints out
|
|
information every time @code{malloc} or @code{free} is called. We just
|
|
assume here that @code{realloc} and @code{memalign} are not used in our
|
|
program.
|
|
|
|
@smallexample
|
|
/* Global variables used to hold underlaying hook values. */
|
|
static void *(*old_malloc_hook) (size_t);
|
|
static void (*old_free_hook) (void*);
|
|
|
|
/* Prototypes for our hooks. */
|
|
static void *my_init_hook (void);
|
|
static void *my_malloc_hook (size_t);
|
|
static void my_free_hook (void*);
|
|
|
|
/* Override initializing hook from the C library. */
|
|
void (*__malloc_initialize_hook) (void) = my_init_hook;
|
|
|
|
static void
|
|
my_init_hook (void)
|
|
@{
|
|
old_malloc_hook = __malloc_hook;
|
|
old_free_hook = __free_hook;
|
|
__malloc_hook = my_malloc_hook;
|
|
__free_hook = my_free_hook;
|
|
@}
|
|
|
|
static void *
|
|
my_malloc_hook (size_t size)
|
|
@{
|
|
void *result;
|
|
/* Restore all old hooks */
|
|
__malloc_hook = old_malloc_hook;
|
|
__free_hook = old_free_hook;
|
|
/* Call recursively */
|
|
result = malloc (size);
|
|
/* Save underlaying hooks */
|
|
old_malloc_hook = __malloc_hook;
|
|
old_free_hook = __free_hook;
|
|
/* @r{@code{printf} might call @code{malloc}, so protect it too.} */
|
|
printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
|
|
/* Restore our own hooks */
|
|
__malloc_hook = my_malloc_hook;
|
|
__free_hook = my_free_hook;
|
|
return result;
|
|
@}
|
|
|
|
static void *
|
|
my_free_hook (void *ptr)
|
|
@{
|
|
/* Restore all old hooks */
|
|
__malloc_hook = old_malloc_hook;
|
|
__free_hook = old_free_hook;
|
|
/* Call recursively */
|
|
free (ptr);
|
|
/* Save underlaying hooks */
|
|
old_malloc_hook = __malloc_hook;
|
|
old_free_hook = __free_hook;
|
|
/* @r{@code{printf} might call @code{free}, so protect it too.} */
|
|
printf ("freed pointer %p\n", ptr);
|
|
/* Restore our own hooks */
|
|
__malloc_hook = my_malloc_hook;
|
|
__free_hook = my_free_hook;
|
|
@}
|
|
|
|
main ()
|
|
@{
|
|
...
|
|
@}
|
|
@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{mallinfo} function. This function and its associated data type
|
|
are declared in @file{malloc.h}; they are an extension of the standard
|
|
SVID/XPG version.
|
|
@pindex malloc.h
|
|
|
|
@comment malloc.h
|
|
@comment GNU
|
|
@deftp {Data Type} {struct mallinfo}
|
|
This structure type is used to return information about the dynamic
|
|
storage allocator. It contains the following members:
|
|
|
|
@table @code
|
|
@item int arena
|
|
This is the total size of memory allocated with @code{sbrk} by
|
|
@code{malloc}, in bytes.
|
|
|
|
@item int ordblks
|
|
This is the number of chunks not 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 int smblks
|
|
This field is unused.
|
|
|
|
@item int hblks
|
|
This is the total number of chunks allocated with @code{mmap}.
|
|
|
|
@item int hblkhd
|
|
This is the total size of memory allocated with @code{mmap}, in bytes.
|
|
|
|
@item int usmblks
|
|
This field is unused.
|
|
|
|
@item int fsmblks
|
|
This field is unused.
|
|
|
|
@item int uordblks
|
|
This is the total size of memory occupied by chunks handed out by
|
|
@code{malloc}.
|
|
|
|
@item int fordblks
|
|
This is the total size of memory occupied by free (not in use) chunks.
|
|
|
|
@item int keepcost
|
|
This is the size of the top-most releasable chunk that normally
|
|
borders the end of the heap (i.e. the ``brk'' of the process).
|
|
|
|
@end table
|
|
@end deftp
|
|
|
|
@comment malloc.h
|
|
@comment SVID
|
|
@deftypefun {struct mallinfo} mallinfo (void)
|
|
This function returns information about the current dynamic memory usage
|
|
in a structure of type @code{struct mallinfo}.
|
|
@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}.
|
|
|
|
@item void *realloc (void *@var{addr}, size_t @var{size})
|
|
Make a block previously allocated by @code{malloc} larger or smaller,
|
|
possibly by copying it to a new location. @xref{Changing Block Size}.
|
|
|
|
@item void *calloc (size_t @var{count}, size_t @var{eltsize})
|
|
Allocate a block of @var{count} * @var{eltsize} bytes using
|
|
@code{malloc}, and set its contents to zero. @xref{Allocating Cleared
|
|
Space}.
|
|
|
|
@item void *valloc (size_t @var{size})
|
|
Allocate a block of @var{size} bytes, starting on a page boundary.
|
|
@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}.
|
|
|
|
@item int mallopt (int @var{param}, int @var{value})
|
|
Adjust a tunable parameter. @xref{Malloc Tunable Parameters}.
|
|
|
|
@item int mcheck (void (*@var{abortfn}) (void))
|
|
Tell @code{malloc} to perform occasional consistency checks on
|
|
dynamically allocated memory, and to call @var{abortfn} when an
|
|
inconsistency is found. @xref{Heap Consistency Checking}.
|
|
|
|
@item void *(*__malloc_hook) (size_t @var{size}, void *@var{caller})
|
|
A pointer to a function that @code{malloc} uses whenever it is called.
|
|
|
|
@item void *(*__realloc_hook) (void *@var{ptr}, size_t @var{size}, void *@var{caller})
|
|
A pointer to a function that @code{realloc} uses whenever it is called.
|
|
|
|
@item void (*__free_hook) (void *@var{ptr}, void *@var{caller})
|
|
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})
|
|
A pointer to a function that @code{memalign} uses whenever it is called.
|
|
|
|
@item struct mallinfo mallinfo (void)
|
|
Return information about the current dynamic memory usage.
|
|
@xref{Statistics of Malloc}.
|
|
@end table
|
|
|
|
@node Allocation Debugging
|
|
@section Allocation Debugging
|
|
@cindex allocation debugging
|
|
@cindex malloc debugger
|
|
|
|
A complicated task when programming with languages which do not use
|
|
garbage collected dynamic memory allocation is to find memory leaks.
|
|
Long running programs must assure that dynamically allocated objects are
|
|
freed at the end of their lifetime. If this does not happen the system
|
|
runs out of memory, sooner or later.
|
|
|
|
The @code{malloc} implementation in the GNU C library provides some
|
|
simple means to detect such leaks and obtain some information to find
|
|
the location. To do this the application must be started in a special
|
|
mode which is enabled by an environment variable. There are no speed
|
|
penalties for the program if the debugging mode is not enabled.
|
|
|
|
@menu
|
|
* Tracing malloc:: How to install the tracing functionality.
|
|
* Using the Memory Debugger:: Example programs excerpts.
|
|
* Tips for the Memory Debugger:: Some more or less clever ideas.
|
|
* Interpreting the traces:: What do all these lines mean?
|
|
@end menu
|
|
|
|
@node Tracing malloc
|
|
@subsection How to install the tracing functionality
|
|
|
|
@comment mcheck.h
|
|
@comment GNU
|
|
@deftypefun void mtrace (void)
|
|
When the @code{mtrace} function is called it looks for an environment
|
|
variable named @code{MALLOC_TRACE}. This variable is supposed to
|
|
contain a valid file name. The user must have write access. If the
|
|
file already exists it is truncated. If the environment variable is not
|
|
set or it does not name a valid file which can be opened for writing
|
|
nothing is done. The behaviour of @code{malloc} etc. is not changed.
|
|
For obvious reasons this also happens if the application is installed
|
|
with the SUID or SGID bit set.
|
|
|
|
If the named file is successfully opened, @code{mtrace} installs special
|
|
handlers for the functions @code{malloc}, @code{realloc}, and
|
|
@code{free} (@pxref{Hooks for Malloc}). From then on, all uses of these
|
|
functions are traced and protocolled into the file. There is now of
|
|
course a speed penalty for all calls to the traced functions so tracing
|
|
should not be enabled during normal use.
|
|
|
|
This function is a GNU extension and generally not available on other
|
|
systems. The prototype can be found in @file{mcheck.h}.
|
|
@end deftypefun
|
|
|
|
@comment mcheck.h
|
|
@comment GNU
|
|
@deftypefun void muntrace (void)
|
|
The @code{muntrace} function can be called after @code{mtrace} was used
|
|
to enable tracing the @code{malloc} calls. If no (succesful) call of
|
|
@code{mtrace} was made @code{muntrace} does nothing.
|
|
|
|
Otherwise it deinstalls the handlers for @code{malloc}, @code{realloc},
|
|
and @code{free} and then closes the protocol file. No calls are
|
|
protocolled anymore and the program runs again at full speed.
|
|
|
|
This function is a GNU extension and generally not available on other
|
|
systems. The prototype can be found in @file{mcheck.h}.
|
|
@end deftypefun
|
|
|
|
@node Using the Memory Debugger
|
|
@subsection Example program excerpts
|
|
|
|
Even though the tracing functionality does not influence the runtime
|
|
behaviour of the program it is not a good idea to call @code{mtrace} in
|
|
all programs. Just imagine that you debug a program using @code{mtrace}
|
|
and all other programs used in the debugging session also trace their
|
|
@code{malloc} calls. The output file would be the same for all programs
|
|
and thus is unusable. Therefore one should call @code{mtrace} only if
|
|
compiled for debugging. A program could therefore start like this:
|
|
|
|
@example
|
|
#include <mcheck.h>
|
|
|
|
int
|
|
main (int argc, char *argv[])
|
|
@{
|
|
#ifdef DEBUGGING
|
|
mtrace ();
|
|
#endif
|
|
@dots{}
|
|
@}
|
|
@end example
|
|
|
|
This is all what is needed if you want to trace the calls during the
|
|
whole runtime of the program. Alternatively you can stop the tracing at
|
|
any time with a call to @code{muntrace}. It is even possible to restart
|
|
the tracing again with a new call to @code{mtrace}. But this can cause
|
|
unreliable results since there may be calls of the functions which are
|
|
not called. Please note that not only the application uses the traced
|
|
functions, also libraries (including the C library itself) use these
|
|
functions.
|
|
|
|
This last point is also why it is no good idea to call @code{muntrace}
|
|
before the program terminated. The libraries are informed about the
|
|
termination of the program only after the program returns from
|
|
@code{main} or calls @code{exit} and so cannot free the memory they use
|
|
before this time.
|
|
|
|
So the best thing one can do is to call @code{mtrace} as the very first
|
|
function in the program and never call @code{muntrace}. So the program
|
|
traces almost all uses of the @code{malloc} functions (except those
|
|
calls which are executed by constructors of the program or used
|
|
libraries).
|
|
|
|
@node Tips for the Memory Debugger
|
|
@subsection Some more or less clever ideas
|
|
|
|
You know the situation. The program is prepared for debugging and in
|
|
all debugging sessions it runs well. But once it is started without
|
|
debugging the error shows up. A typical example is a memory leak that
|
|
becomes visible only when we turn off the debugging. If you foresee
|
|
such situations you can still win. Simply use something equivalent to
|
|
the following little program:
|
|
|
|
@example
|
|
#include <mcheck.h>
|
|
#include <signal.h>
|
|
|
|
static void
|
|
enable (int sig)
|
|
@{
|
|
mtrace ();
|
|
signal (SIGUSR1, enable);
|
|
@}
|
|
|
|
static void
|
|
disable (int sig)
|
|
@{
|
|
muntrace ();
|
|
signal (SIGUSR2, disable);
|
|
@}
|
|
|
|
int
|
|
main (int argc, char *argv[])
|
|
@{
|
|
@dots{}
|
|
|
|
signal (SIGUSR1, enable);
|
|
signal (SIGUSR2, disable);
|
|
|
|
@dots{}
|
|
@}
|
|
@end example
|
|
|
|
I.e., the user can start the memory debugger any time s/he wants if the
|
|
program was started with @code{MALLOC_TRACE} set in the environment.
|
|
The output will of course not show the allocations which happened before
|
|
the first signal but if there is a memory leak this will show up
|
|
nevertheless.
|
|
|
|
@node Interpreting the traces
|
|
@subsection Interpreting the traces
|
|
|
|
If you take a look at the output it will look similar to this:
|
|
|
|
@example
|
|
= Start
|
|
@ [0x8048209] - 0x8064cc8
|
|
@ [0x8048209] - 0x8064ce0
|
|
@ [0x8048209] - 0x8064cf8
|
|
@ [0x80481eb] + 0x8064c48 0x14
|
|
@ [0x80481eb] + 0x8064c60 0x14
|
|
@ [0x80481eb] + 0x8064c78 0x14
|
|
@ [0x80481eb] + 0x8064c90 0x14
|
|
= End
|
|
@end example
|
|
|
|
What this all means is not really important since the trace file is not
|
|
meant to be read by a human. Therefore no attention is given to
|
|
readability. Instead there is a program which comes with the GNU C
|
|
library which interprets the traces and outputs a summary in an
|
|
user-friendly way. The program is called @code{mtrace} (it is in fact a
|
|
Perl script) and it takes one or two arguments. In any case the name of
|
|
the file with the trace output must be specified. If an optional
|
|
argument precedes the name of the trace file this must be the name of
|
|
the program which generated the trace.
|
|
|
|
@example
|
|
drepper$ mtrace tst-mtrace log
|
|
No memory leaks.
|
|
@end example
|
|
|
|
In this case the program @code{tst-mtrace} was run and it produced a
|
|
trace file @file{log}. The message printed by @code{mtrace} shows there
|
|
are no problems with the code, all allocated memory was freed
|
|
afterwards.
|
|
|
|
If we call @code{mtrace} on the example trace given above we would get a
|
|
different outout:
|
|
|
|
@example
|
|
drepper$ mtrace errlog
|
|
- 0x08064cc8 Free 2 was never alloc'd 0x8048209
|
|
- 0x08064ce0 Free 3 was never alloc'd 0x8048209
|
|
- 0x08064cf8 Free 4 was never alloc'd 0x8048209
|
|
|
|
Memory not freed:
|
|
-----------------
|
|
Address Size Caller
|
|
0x08064c48 0x14 at 0x80481eb
|
|
0x08064c60 0x14 at 0x80481eb
|
|
0x08064c78 0x14 at 0x80481eb
|
|
0x08064c90 0x14 at 0x80481eb
|
|
@end example
|
|
|
|
We have called @code{mtrace} with only one argument and so the script
|
|
has no chance to find out what is meant with the addresses given in the
|
|
trace. We can do better:
|
|
|
|
@example
|
|
drepper$ mtrace tst errlog
|
|
- 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
|
|
- 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
|
|
- 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39
|
|
|
|
Memory not freed:
|
|
-----------------
|
|
Address Size Caller
|
|
0x08064c48 0x14 at /home/drepper/tst.c:33
|
|
0x08064c60 0x14 at /home/drepper/tst.c:33
|
|
0x08064c78 0x14 at /home/drepper/tst.c:33
|
|
0x08064c90 0x14 at /home/drepper/tst.c:33
|
|
@end example
|
|
|
|
Suddenly the output makes much more sense and the user can see
|
|
immediately where the function calls causing the trouble can be found.
|
|
|
|
Interpreting this output is not complicated. There are at most two
|
|
different situations being detected. First, @code{free} was called for
|
|
pointers which were never returned by one of the allocation functions.
|
|
This is usually a very bad problem and what this looks like is shown in
|
|
the first three lines of the output. Situations like this are quite
|
|
rare and if they appear they show up very drastically: the program
|
|
normally crashes.
|
|
|
|
The other situation which is much harder to detect are memory leaks. As
|
|
you can see in the output the @code{mtrace} function collects all this
|
|
information and so can say that the program calls an allocation function
|
|
from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
|
|
times without freeing this memory before the program terminates.
|
|
Whether this is a real problem remains to be investigated.
|
|
|
|
@node Obstacks
|
|
@section Obstacks
|
|
@cindex obstacks
|
|
|
|
An @dfn{obstack} is a pool of memory containing a stack of objects. You
|
|
can create any number of separate obstacks, and then allocate objects in
|
|
specified obstacks. Within each obstack, the last object allocated must
|
|
always be the first one freed, but distinct obstacks are independent of
|
|
each other.
|
|
|
|
Aside from this one constraint of order of freeing, obstacks are totally
|
|
general: an obstack can contain any number of objects of any size. They
|
|
are implemented with macros, so allocation is usually very fast as long as
|
|
the objects are usually small. And the only space overhead per object is
|
|
the padding needed to start each object on a suitable boundary.
|
|
|
|
@menu
|
|
* Creating Obstacks:: How to declare an obstack in your program.
|
|
* Preparing for Obstacks:: Preparations needed before you can
|
|
use obstacks.
|
|
* Allocation in an Obstack:: Allocating objects in an obstack.
|
|
* Freeing Obstack Objects:: Freeing objects in an obstack.
|
|
* Obstack Functions:: The obstack functions are both
|
|
functions and macros.
|
|
* Growing Objects:: Making an object bigger by stages.
|
|
* Extra Fast Growing:: Extra-high-efficiency (though more
|
|
complicated) growing objects.
|
|
* Status of an Obstack:: Inquiries about the status of an obstack.
|
|
* Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
|
|
* Obstack Chunks:: How obstacks obtain and release chunks;
|
|
efficiency considerations.
|
|
* Summary of Obstacks::
|
|
@end menu
|
|
|
|
@node Creating Obstacks
|
|
@subsection Creating Obstacks
|
|
|
|
The utilities for manipulating obstacks are declared in the header
|
|
file @file{obstack.h}.
|
|
@pindex obstack.h
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftp {Data Type} {struct obstack}
|
|
An obstack is represented by a data structure of type @code{struct
|
|
obstack}. This structure has a small fixed size; it records the status
|
|
of the obstack and how to find the space in which objects are allocated.
|
|
It does not contain any of the objects themselves. You should not try
|
|
to access the contents of the structure directly; use only the functions
|
|
described in this chapter.
|
|
@end deftp
|
|
|
|
You can declare variables of type @code{struct obstack} and use them as
|
|
obstacks, or you can allocate obstacks dynamically like any other kind
|
|
of object. Dynamic allocation of obstacks allows your program to have a
|
|
variable number of different stacks. (You can even allocate an
|
|
obstack structure in another obstack, but this is rarely useful.)
|
|
|
|
All the functions that work with obstacks require you to specify which
|
|
obstack to use. You do this with a pointer of type @code{struct obstack
|
|
*}. In the following, we often say ``an obstack'' when strictly
|
|
speaking the object at hand is such a pointer.
|
|
|
|
The objects in the obstack are packed into large blocks called
|
|
@dfn{chunks}. The @code{struct obstack} structure points to a chain of
|
|
the chunks currently in use.
|
|
|
|
The obstack library obtains a new chunk whenever you allocate an object
|
|
that won't fit in the previous chunk. Since the obstack library manages
|
|
chunks automatically, you don't need to pay much attention to them, but
|
|
you do need to supply a function which the obstack library should use to
|
|
get a chunk. Usually you supply a function which uses @code{malloc}
|
|
directly or indirectly. You must also supply a function to free a chunk.
|
|
These matters are described in the following section.
|
|
|
|
@node Preparing for Obstacks
|
|
@subsection Preparing for Using Obstacks
|
|
|
|
Each source file in which you plan to use the obstack functions
|
|
must include the header file @file{obstack.h}, like this:
|
|
|
|
@smallexample
|
|
#include <obstack.h>
|
|
@end smallexample
|
|
|
|
@findex obstack_chunk_alloc
|
|
@findex obstack_chunk_free
|
|
Also, if the source file uses the macro @code{obstack_init}, it must
|
|
declare or define two functions or macros that will be called by the
|
|
obstack library. One, @code{obstack_chunk_alloc}, is used to allocate
|
|
the chunks of memory into which objects are packed. The other,
|
|
@code{obstack_chunk_free}, is used to return chunks when the objects in
|
|
them are freed. These macros should appear before any use of obstacks
|
|
in the source file.
|
|
|
|
Usually these are defined to use @code{malloc} via the intermediary
|
|
@code{xmalloc} (@pxref{Unconstrained Allocation}). This is done with
|
|
the following pair of macro definitions:
|
|
|
|
@smallexample
|
|
#define obstack_chunk_alloc xmalloc
|
|
#define obstack_chunk_free free
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Though the storage you get using obstacks really comes from @code{malloc},
|
|
using obstacks is faster because @code{malloc} is called less often, for
|
|
larger blocks of memory. @xref{Obstack Chunks}, for full details.
|
|
|
|
At run time, before the program can use a @code{struct obstack} object
|
|
as an obstack, it must initialize the obstack by calling
|
|
@code{obstack_init}.
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
|
|
Initialize obstack @var{obstack-ptr} for allocation of objects. This
|
|
function calls the obstack's @code{obstack_chunk_alloc} function. If
|
|
allocation of memory fails, the function pointed to by
|
|
@code{obstack_alloc_failed_handler} is called. The @code{obstack_init}
|
|
function always returns 1 (Compatibility notice: Former versions of
|
|
obstack returned 0 if allocation failed).
|
|
@end deftypefun
|
|
|
|
Here are two examples of how to allocate the space for an obstack and
|
|
initialize it. First, an obstack that is a static variable:
|
|
|
|
@smallexample
|
|
static struct obstack myobstack;
|
|
@dots{}
|
|
obstack_init (&myobstack);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Second, an obstack that is itself dynamically allocated:
|
|
|
|
@smallexample
|
|
struct obstack *myobstack_ptr
|
|
= (struct obstack *) xmalloc (sizeof (struct obstack));
|
|
|
|
obstack_init (myobstack_ptr);
|
|
@end smallexample
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@defvar obstack_alloc_failed_handler
|
|
The value of this variable is a pointer to a function that
|
|
@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
|
|
memory. The default action is to print a message and abort.
|
|
You should supply a function that either calls @code{exit}
|
|
(@pxref{Program Termination}) or @code{longjmp} (@pxref{Non-Local
|
|
Exits}) and doesn't return.
|
|
|
|
@smallexample
|
|
void my_obstack_alloc_failed (void)
|
|
@dots{}
|
|
obstack_alloc_failed_handler = &my_obstack_alloc_failed;
|
|
@end smallexample
|
|
|
|
@end defvar
|
|
|
|
@node Allocation in an Obstack
|
|
@subsection Allocation in an Obstack
|
|
@cindex allocation (obstacks)
|
|
|
|
The most direct way to allocate an object in an obstack is with
|
|
@code{obstack_alloc}, which is invoked almost like @code{malloc}.
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
|
|
This allocates an uninitialized block of @var{size} bytes in an obstack
|
|
and returns its address. Here @var{obstack-ptr} specifies which obstack
|
|
to allocate the block in; it is the address of the @code{struct obstack}
|
|
object which represents the obstack. Each obstack function or macro
|
|
requires you to specify an @var{obstack-ptr} as the first argument.
|
|
|
|
This function calls the obstack's @code{obstack_chunk_alloc} function if
|
|
it needs to allocate a new chunk of memory; it calls
|
|
@code{obstack_alloc_failed_handler} if allocation of memory by
|
|
@code{obstack_chunk_alloc} failed.
|
|
@end deftypefun
|
|
|
|
For example, here is a function that allocates a copy of a string @var{str}
|
|
in a specific obstack, which is in the variable @code{string_obstack}:
|
|
|
|
@smallexample
|
|
struct obstack string_obstack;
|
|
|
|
char *
|
|
copystring (char *string)
|
|
@{
|
|
size_t len = strlen (string) + 1;
|
|
char *s = (char *) obstack_alloc (&string_obstack, len);
|
|
memcpy (s, string, len);
|
|
return s;
|
|
@}
|
|
@end smallexample
|
|
|
|
To allocate a block with specified contents, use the function
|
|
@code{obstack_copy}, declared like this:
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
|
|
This allocates a block and initializes it by copying @var{size}
|
|
bytes of data starting at @var{address}. It calls
|
|
@code{obstack_alloc_failed_handler} if allocation of memory by
|
|
@code{obstack_chunk_alloc} failed.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
|
|
Like @code{obstack_copy}, but appends an extra byte containing a null
|
|
character. This extra byte is not counted in the argument @var{size}.
|
|
@end deftypefun
|
|
|
|
The @code{obstack_copy0} function is convenient for copying a sequence
|
|
of characters into an obstack as a null-terminated string. Here is an
|
|
example of its use:
|
|
|
|
@smallexample
|
|
char *
|
|
obstack_savestring (char *addr, int size)
|
|
@{
|
|
return obstack_copy0 (&myobstack, addr, size);
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Contrast this with the previous example of @code{savestring} using
|
|
@code{malloc} (@pxref{Basic Allocation}).
|
|
|
|
@node Freeing Obstack Objects
|
|
@subsection Freeing Objects in an Obstack
|
|
@cindex freeing (obstacks)
|
|
|
|
To free an object allocated in an obstack, use the function
|
|
@code{obstack_free}. Since the obstack is a stack of objects, freeing
|
|
one object automatically frees all other objects allocated more recently
|
|
in the same obstack.
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
|
|
If @var{object} is a null pointer, everything allocated in the obstack
|
|
is freed. Otherwise, @var{object} must be the address of an object
|
|
allocated in the obstack. Then @var{object} is freed, along with
|
|
everything allocated in @var{obstack} since @var{object}.
|
|
@end deftypefun
|
|
|
|
Note that if @var{object} is a null pointer, the result is an
|
|
uninitialized obstack. To free all storage in an obstack but leave it
|
|
valid for further allocation, call @code{obstack_free} with the address
|
|
of the first object allocated on the obstack:
|
|
|
|
@smallexample
|
|
obstack_free (obstack_ptr, first_object_allocated_ptr);
|
|
@end smallexample
|
|
|
|
Recall that the objects in an obstack are grouped into chunks. When all
|
|
the objects in a chunk become free, the obstack library automatically
|
|
frees the chunk (@pxref{Preparing for Obstacks}). Then other
|
|
obstacks, or non-obstack allocation, can reuse the space of the chunk.
|
|
|
|
@node Obstack Functions
|
|
@subsection Obstack Functions and Macros
|
|
@cindex macros
|
|
|
|
The interfaces for using obstacks may be defined either as functions or
|
|
as macros, depending on the compiler. The obstack facility works with
|
|
all C compilers, including both @w{ISO C} and traditional C, but there are
|
|
precautions you must take if you plan to use compilers other than GNU C.
|
|
|
|
If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack
|
|
``functions'' are actually defined only as macros. You can call these
|
|
macros like functions, but you cannot use them in any other way (for
|
|
example, you cannot take their address).
|
|
|
|
Calling the macros requires a special precaution: namely, the first
|
|
operand (the obstack pointer) may not contain any side effects, because
|
|
it may be computed more than once. For example, if you write this:
|
|
|
|
@smallexample
|
|
obstack_alloc (get_obstack (), 4);
|
|
@end smallexample
|
|
|
|
@noindent
|
|
you will find that @code{get_obstack} may be called several times.
|
|
If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
|
|
you will get very strange results since the incrementation may occur
|
|
several times.
|
|
|
|
In @w{ISO C}, each function has both a macro definition and a function
|
|
definition. The function definition is used if you take the address of the
|
|
function without calling it. An ordinary call uses the macro definition by
|
|
default, but you can request the function definition instead by writing the
|
|
function name in parentheses, as shown here:
|
|
|
|
@smallexample
|
|
char *x;
|
|
void *(*funcp) ();
|
|
/* @r{Use the macro}. */
|
|
x = (char *) obstack_alloc (obptr, size);
|
|
/* @r{Call the function}. */
|
|
x = (char *) (obstack_alloc) (obptr, size);
|
|
/* @r{Take the address of the function}. */
|
|
funcp = obstack_alloc;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This is the same situation that exists in @w{ISO C} for the standard library
|
|
functions. @xref{Macro Definitions}.
|
|
|
|
@strong{Warning:} When you do use the macros, you must observe the
|
|
precaution of avoiding side effects in the first operand, even in @w{ISO C}.
|
|
|
|
If you use the GNU C compiler, this precaution is not necessary, because
|
|
various language extensions in GNU C permit defining the macros so as to
|
|
compute each argument only once.
|
|
|
|
@node Growing Objects
|
|
@subsection Growing Objects
|
|
@cindex growing objects (in obstacks)
|
|
@cindex changing the size of a block (obstacks)
|
|
|
|
Because storage in obstack chunks is used sequentially, it is possible to
|
|
build up an object step by step, adding one or more bytes at a time to the
|
|
end of the object. With this technique, you do not need to know how much
|
|
data you will put in the object until you come to the end of it. We call
|
|
this the technique of @dfn{growing objects}. The special functions
|
|
for adding data to the growing object are described in this section.
|
|
|
|
You don't need to do anything special when you start to grow an object.
|
|
Using one of the functions to add data to the object automatically
|
|
starts it. However, it is necessary to say explicitly when the object is
|
|
finished. This is done with the function @code{obstack_finish}.
|
|
|
|
The actual address of the object thus built up is not known until the
|
|
object is finished. Until then, it always remains possible that you will
|
|
add so much data that the object must be copied into a new chunk.
|
|
|
|
While the obstack is in use for a growing object, you cannot use it for
|
|
ordinary allocation of another object. If you try to do so, the space
|
|
already added to the growing object will become part of the other object.
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
|
|
The most basic function for adding to a growing object is
|
|
@code{obstack_blank}, which adds space without initializing it.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
|
|
To add a block of initialized space, use @code{obstack_grow}, which is
|
|
the growing-object analogue of @code{obstack_copy}. It adds @var{size}
|
|
bytes of data to the growing object, copying the contents from
|
|
@var{data}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
|
|
This is the growing-object analogue of @code{obstack_copy0}. It adds
|
|
@var{size} bytes copied from @var{data}, followed by an additional null
|
|
character.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
|
|
To add one character at a time, use the function @code{obstack_1grow}.
|
|
It adds a single byte containing @var{c} to the growing object.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
|
|
Adding the value of a pointer one can use the function
|
|
@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes
|
|
containing the value of @var{data}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
|
|
A single value of type @code{int} can be added by using the
|
|
@code{obstack_int_grow} function. It adds @code{sizeof (int)} bytes to
|
|
the growing object and initializes them with the value of @var{data}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
|
|
When you are finished growing the object, use the function
|
|
@code{obstack_finish} to close it off and return its final address.
|
|
|
|
Once you have finished the object, the obstack is available for ordinary
|
|
allocation or for growing another object.
|
|
|
|
This function can return a null pointer under the same conditions as
|
|
@code{obstack_alloc} (@pxref{Allocation in an Obstack}).
|
|
@end deftypefun
|
|
|
|
When you build an object by growing it, you will probably need to know
|
|
afterward how long it became. You need not keep track of this as you grow
|
|
the object, because you can find out the length from the obstack just
|
|
before finishing the object with the function @code{obstack_object_size},
|
|
declared as follows:
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
|
|
This function returns the current size of the growing object, in bytes.
|
|
Remember to call this function @emph{before} finishing the object.
|
|
After it is finished, @code{obstack_object_size} will return zero.
|
|
@end deftypefun
|
|
|
|
If you have started growing an object and wish to cancel it, you should
|
|
finish it and then free it, like this:
|
|
|
|
@smallexample
|
|
obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
This has no effect if no object was growing.
|
|
|
|
@cindex shrinking objects
|
|
You can use @code{obstack_blank} with a negative size argument to make
|
|
the current object smaller. Just don't try to shrink it beyond zero
|
|
length---there's no telling what will happen if you do that.
|
|
|
|
@node Extra Fast Growing
|
|
@subsection Extra Fast Growing Objects
|
|
@cindex efficiency and obstacks
|
|
|
|
The usual functions for growing objects incur overhead for checking
|
|
whether there is room for the new growth in the current chunk. If you
|
|
are frequently constructing objects in small steps of growth, this
|
|
overhead can be significant.
|
|
|
|
You can reduce the overhead by using special ``fast growth''
|
|
functions that grow the object without checking. In order to have a
|
|
robust program, you must do the checking yourself. If you do this checking
|
|
in the simplest way each time you are about to add data to the object, you
|
|
have not saved anything, because that is what the ordinary growth
|
|
functions do. But if you can arrange to check less often, or check
|
|
more efficiently, then you make the program faster.
|
|
|
|
The function @code{obstack_room} returns the amount of room available
|
|
in the current chunk. It is declared as follows:
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
|
|
This returns the number of bytes that can be added safely to the current
|
|
growing object (or to an object about to be started) in obstack
|
|
@var{obstack} using the fast growth functions.
|
|
@end deftypefun
|
|
|
|
While you know there is room, you can use these fast growth functions
|
|
for adding data to a growing object:
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
|
|
The function @code{obstack_1grow_fast} adds one byte containing the
|
|
character @var{c} to the growing object in obstack @var{obstack-ptr}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
|
|
The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
|
|
bytes containing the value of @var{data} to the growing object in
|
|
obstack @var{obstack-ptr}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
|
|
The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
|
|
containing the value of @var{data} to the growing object in obstack
|
|
@var{obstack-ptr}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
|
|
The function @code{obstack_blank_fast} adds @var{size} bytes to the
|
|
growing object in obstack @var{obstack-ptr} without initializing them.
|
|
@end deftypefun
|
|
|
|
When you check for space using @code{obstack_room} and there is not
|
|
enough room for what you want to add, the fast growth functions
|
|
are not safe. In this case, simply use the corresponding ordinary
|
|
growth function instead. Very soon this will copy the object to a
|
|
new chunk; then there will be lots of room available again.
|
|
|
|
So, each time you use an ordinary growth function, check afterward for
|
|
sufficient space using @code{obstack_room}. Once the object is copied
|
|
to a new chunk, there will be plenty of space again, so the program will
|
|
start using the fast growth functions again.
|
|
|
|
Here is an example:
|
|
|
|
@smallexample
|
|
@group
|
|
void
|
|
add_string (struct obstack *obstack, const char *ptr, int len)
|
|
@{
|
|
while (len > 0)
|
|
@{
|
|
int room = obstack_room (obstack);
|
|
if (room == 0)
|
|
@{
|
|
/* @r{Not enough room. Add one character slowly,}
|
|
@r{which may copy to a new chunk and make room.} */
|
|
obstack_1grow (obstack, *ptr++);
|
|
len--;
|
|
@}
|
|
else
|
|
@{
|
|
if (room > len)
|
|
room = len;
|
|
/* @r{Add fast as much as we have room for.} */
|
|
len -= room;
|
|
while (room-- > 0)
|
|
obstack_1grow_fast (obstack, *ptr++);
|
|
@}
|
|
@}
|
|
@}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@node Status of an Obstack
|
|
@subsection Status of an Obstack
|
|
@cindex obstack status
|
|
@cindex status of obstack
|
|
|
|
Here are functions that provide information on the current status of
|
|
allocation in an obstack. You can use them to learn about an object while
|
|
still growing it.
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
|
|
This function returns the tentative address of the beginning of the
|
|
currently growing object in @var{obstack-ptr}. If you finish the object
|
|
immediately, it will have that address. If you make it larger first, it
|
|
may outgrow the current chunk---then its address will change!
|
|
|
|
If no object is growing, this value says where the next object you
|
|
allocate will start (once again assuming it fits in the current
|
|
chunk).
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
|
|
This function returns the address of the first free byte in the current
|
|
chunk of obstack @var{obstack-ptr}. This is the end of the currently
|
|
growing object. If no object is growing, @code{obstack_next_free}
|
|
returns the same value as @code{obstack_base}.
|
|
@end deftypefun
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
|
|
This function returns the size in bytes of the currently growing object.
|
|
This is equivalent to
|
|
|
|
@smallexample
|
|
obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
|
|
@end smallexample
|
|
@end deftypefun
|
|
|
|
@node Obstacks Data Alignment
|
|
@subsection Alignment of Data in Obstacks
|
|
@cindex alignment (in obstacks)
|
|
|
|
Each obstack has an @dfn{alignment boundary}; each object allocated in
|
|
the obstack automatically starts on an address that is a multiple of the
|
|
specified boundary. By default, this boundary is 4 bytes.
|
|
|
|
To access an obstack's alignment boundary, use the macro
|
|
@code{obstack_alignment_mask}, whose function prototype looks like
|
|
this:
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
|
|
The value is a bit mask; a bit that is 1 indicates that the corresponding
|
|
bit in the address of an object should be 0. The mask value should be one
|
|
less than a power of 2; the effect is that all object addresses are
|
|
multiples of that power of 2. The default value of the mask is 3, so that
|
|
addresses are multiples of 4. A mask value of 0 means an object can start
|
|
on any multiple of 1 (that is, no alignment is required).
|
|
|
|
The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
|
|
so you can alter the mask by assignment. For example, this statement:
|
|
|
|
@smallexample
|
|
obstack_alignment_mask (obstack_ptr) = 0;
|
|
@end smallexample
|
|
|
|
@noindent
|
|
has the effect of turning off alignment processing in the specified obstack.
|
|
@end deftypefn
|
|
|
|
Note that a change in alignment mask does not take effect until
|
|
@emph{after} the next time an object is allocated or finished in the
|
|
obstack. If you are not growing an object, you can make the new
|
|
alignment mask take effect immediately by calling @code{obstack_finish}.
|
|
This will finish a zero-length object and then do proper alignment for
|
|
the next object.
|
|
|
|
@node Obstack Chunks
|
|
@subsection Obstack Chunks
|
|
@cindex efficiency of chunks
|
|
@cindex chunks
|
|
|
|
Obstacks work by allocating space for themselves in large chunks, and
|
|
then parceling out space in the chunks to satisfy your requests. Chunks
|
|
are normally 4096 bytes long unless you specify a different chunk size.
|
|
The chunk size includes 8 bytes of overhead that are not actually used
|
|
for storing objects. Regardless of the specified size, longer chunks
|
|
will be allocated when necessary for long objects.
|
|
|
|
The obstack library allocates chunks by calling the function
|
|
@code{obstack_chunk_alloc}, which you must define. When a chunk is no
|
|
longer needed because you have freed all the objects in it, the obstack
|
|
library frees the chunk by calling @code{obstack_chunk_free}, which you
|
|
must also define.
|
|
|
|
These two must be defined (as macros) or declared (as functions) in each
|
|
source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
|
|
Most often they are defined as macros like this:
|
|
|
|
@smallexample
|
|
#define obstack_chunk_alloc malloc
|
|
#define obstack_chunk_free free
|
|
@end smallexample
|
|
|
|
Note that these are simple macros (no arguments). Macro definitions with
|
|
arguments will not work! It is necessary that @code{obstack_chunk_alloc}
|
|
or @code{obstack_chunk_free}, alone, expand into a function name if it is
|
|
not itself a function name.
|
|
|
|
If you allocate chunks with @code{malloc}, the chunk size should be a
|
|
power of 2. The default chunk size, 4096, was chosen because it is long
|
|
enough to satisfy many typical requests on the obstack yet short enough
|
|
not to waste too much memory in the portion of the last chunk not yet used.
|
|
|
|
@comment obstack.h
|
|
@comment GNU
|
|
@deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
|
|
This returns the chunk size of the given obstack.
|
|
@end deftypefn
|
|
|
|
Since this macro expands to an lvalue, you can specify a new chunk size by
|
|
assigning it a new value. Doing so does not affect the chunks already
|
|
allocated, but will change the size of chunks allocated for that particular
|
|
obstack in the future. It is unlikely to be useful to make the chunk size
|
|
smaller, but making it larger might improve efficiency if you are
|
|
allocating many objects whose size is comparable to the chunk size. Here
|
|
is how to do so cleanly:
|
|
|
|
@smallexample
|
|
if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
|
|
obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
|
|
@end smallexample
|
|
|
|
@node Summary of Obstacks
|
|
@subsection Summary of Obstack Functions
|
|
|
|
Here is a summary of all the functions associated with obstacks. Each
|
|
takes the address of an obstack (@code{struct obstack *}) as its first
|
|
argument.
|
|
|
|
@table @code
|
|
@item void obstack_init (struct obstack *@var{obstack-ptr})
|
|
Initialize use of an obstack. @xref{Creating Obstacks}.
|
|
|
|
@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
|
|
Allocate an object of @var{size} uninitialized bytes.
|
|
@xref{Allocation in an Obstack}.
|
|
|
|
@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
|
|
Allocate an object of @var{size} bytes, with contents copied from
|
|
@var{address}. @xref{Allocation in an Obstack}.
|
|
|
|
@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
|
|
Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
|
|
from @var{address}, followed by a null character at the end.
|
|
@xref{Allocation in an Obstack}.
|
|
|
|
@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
|
|
Free @var{object} (and everything allocated in the specified obstack
|
|
more recently than @var{object}). @xref{Freeing Obstack Objects}.
|
|
|
|
@item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
|
|
Add @var{size} uninitialized bytes to a growing object.
|
|
@xref{Growing Objects}.
|
|
|
|
@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
|
|
Add @var{size} bytes, copied from @var{address}, to a growing object.
|
|
@xref{Growing Objects}.
|
|
|
|
@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
|
|
Add @var{size} bytes, copied from @var{address}, to a growing object,
|
|
and then add another byte containing a null character. @xref{Growing
|
|
Objects}.
|
|
|
|
@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
|
|
Add one byte containing @var{data-char} to a growing object.
|
|
@xref{Growing Objects}.
|
|
|
|
@item void *obstack_finish (struct obstack *@var{obstack-ptr})
|
|
Finalize the object that is growing and return its permanent address.
|
|
@xref{Growing Objects}.
|
|
|
|
@item int obstack_object_size (struct obstack *@var{obstack-ptr})
|
|
Get the current size of the currently growing object. @xref{Growing
|
|
Objects}.
|
|
|
|
@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
|
|
Add @var{size} uninitialized bytes to a growing object without checking
|
|
that there is enough room. @xref{Extra Fast Growing}.
|
|
|
|
@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
|
|
Add one byte containing @var{data-char} to a growing object without
|
|
checking that there is enough room. @xref{Extra Fast Growing}.
|
|
|
|
@item int obstack_room (struct obstack *@var{obstack-ptr})
|
|
Get the amount of room now available for growing the current object.
|
|
@xref{Extra Fast Growing}.
|
|
|
|
@item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
|
|
The mask used for aligning the beginning of an object. This is an
|
|
lvalue. @xref{Obstacks Data Alignment}.
|
|
|
|
@item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
|
|
The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}.
|
|
|
|
@item void *obstack_base (struct obstack *@var{obstack-ptr})
|
|
Tentative starting address of the currently growing object.
|
|
@xref{Status of an Obstack}.
|
|
|
|
@item void *obstack_next_free (struct obstack *@var{obstack-ptr})
|
|
Address just after the end of the currently growing object.
|
|
@xref{Status of an Obstack}.
|
|
@end table
|
|
|
|
@node Variable Size Automatic
|
|
@section Automatic Storage with Variable Size
|
|
@cindex automatic freeing
|
|
@cindex @code{alloca} function
|
|
@cindex automatic storage with variable size
|
|
|
|
The function @code{alloca} supports a kind of half-dynamic allocation in
|
|
which blocks are allocated dynamically but freed automatically.
|
|
|
|
Allocating a block with @code{alloca} is an explicit action; you can
|
|
allocate as many blocks as you wish, and compute the size at run time. But
|
|
all the blocks are freed when you exit the function that @code{alloca} was
|
|
called from, just as if they were automatic variables declared in that
|
|
function. There is no way to free the space explicitly.
|
|
|
|
The prototype for @code{alloca} is in @file{stdlib.h}. This function is
|
|
a BSD extension.
|
|
@pindex stdlib.h
|
|
|
|
@comment stdlib.h
|
|
@comment GNU, BSD
|
|
@deftypefun {void *} alloca (size_t @var{size});
|
|
The return value of @code{alloca} is the address of a block of @var{size}
|
|
bytes of storage, allocated in the stack frame of the calling function.
|
|
@end deftypefun
|
|
|
|
Do not use @code{alloca} inside the arguments of a function call---you
|
|
will get unpredictable results, because the stack space for the
|
|
@code{alloca} would appear on the stack in the middle of the space for
|
|
the function arguments. An example of what to avoid is @code{foo (x,
|
|
alloca (4), y)}.
|
|
@c This might get fixed in future versions of GCC, but that won't make
|
|
@c it safe with compilers generally.
|
|
|
|
@menu
|
|
* Alloca Example:: Example of using @code{alloca}.
|
|
* Advantages of Alloca:: Reasons to use @code{alloca}.
|
|
* Disadvantages of Alloca:: Reasons to avoid @code{alloca}.
|
|
* GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative
|
|
method of allocating dynamically and
|
|
freeing automatically.
|
|
@end menu
|
|
|
|
@node Alloca Example
|
|
@subsection @code{alloca} Example
|
|
|
|
As an example of the use of @code{alloca}, here is a function that opens
|
|
a file name made from concatenating two argument strings, and returns a
|
|
file descriptor or minus one signifying failure:
|
|
|
|
@smallexample
|
|
int
|
|
open2 (char *str1, char *str2, int flags, int mode)
|
|
@{
|
|
char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
|
|
stpcpy (stpcpy (name, str1), str2);
|
|
return open (name, flags, mode);
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here is how you would get the same results with @code{malloc} and
|
|
@code{free}:
|
|
|
|
@smallexample
|
|
int
|
|
open2 (char *str1, char *str2, int flags, int mode)
|
|
@{
|
|
char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
|
|
int desc;
|
|
if (name == 0)
|
|
fatal ("virtual memory exceeded");
|
|
stpcpy (stpcpy (name, str1), str2);
|
|
desc = open (name, flags, mode);
|
|
free (name);
|
|
return desc;
|
|
@}
|
|
@end smallexample
|
|
|
|
As you can see, it is simpler with @code{alloca}. But @code{alloca} has
|
|
other, more important advantages, and some disadvantages.
|
|
|
|
@node Advantages of Alloca
|
|
@subsection Advantages of @code{alloca}
|
|
|
|
Here are the reasons why @code{alloca} may be preferable to @code{malloc}:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
Using @code{alloca} wastes very little space and is very fast. (It is
|
|
open-coded by the GNU C compiler.)
|
|
|
|
@item
|
|
Since @code{alloca} does not have separate pools for different sizes of
|
|
block, space used for any size block can be reused for any other size.
|
|
@code{alloca} does not cause storage fragmentation.
|
|
|
|
@item
|
|
@cindex longjmp
|
|
Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
|
|
automatically free the space allocated with @code{alloca} when they exit
|
|
through the function that called @code{alloca}. This is the most
|
|
important reason to use @code{alloca}.
|
|
|
|
To illustrate this, suppose you have a function
|
|
@code{open_or_report_error} which returns a descriptor, like
|
|
@code{open}, if it succeeds, but does not return to its caller if it
|
|
fails. If the file cannot be opened, it prints an error message and
|
|
jumps out to the command level of your program using @code{longjmp}.
|
|
Let's change @code{open2} (@pxref{Alloca Example}) to use this
|
|
subroutine:@refill
|
|
|
|
@smallexample
|
|
int
|
|
open2 (char *str1, char *str2, int flags, int mode)
|
|
@{
|
|
char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
|
|
stpcpy (stpcpy (name, str1), str2);
|
|
return open_or_report_error (name, flags, mode);
|
|
@}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Because of the way @code{alloca} works, the storage it allocates is
|
|
freed even when an error occurs, with no special effort required.
|
|
|
|
By contrast, the previous definition of @code{open2} (which uses
|
|
@code{malloc} and @code{free}) would develop a storage leak if it were
|
|
changed in this way. Even if you are willing to make more changes to
|
|
fix it, there is no easy way to do so.
|
|
@end itemize
|
|
|
|
@node Disadvantages of Alloca
|
|
@subsection Disadvantages of @code{alloca}
|
|
|
|
@cindex @code{alloca} disadvantages
|
|
@cindex disadvantages of @code{alloca}
|
|
These are the disadvantages of @code{alloca} in comparison with
|
|
@code{malloc}:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If you try to allocate more storage than the machine can provide, you
|
|
don't get a clean error message. Instead you get a fatal signal like
|
|
the one you would get from an infinite recursion; probably a
|
|
segmentation violation (@pxref{Program Error Signals}).
|
|
|
|
@item
|
|
Some non-GNU systems fail to support @code{alloca}, so it is less
|
|
portable. However, a slower emulation of @code{alloca} written in C
|
|
is available for use on systems with this deficiency.
|
|
@end itemize
|
|
|
|
@node GNU C Variable-Size Arrays
|
|
@subsection GNU C Variable-Size Arrays
|
|
@cindex variable-sized arrays
|
|
|
|
In GNU C, you can replace most uses of @code{alloca} with an array of
|
|
variable size. Here is how @code{open2} would look then:
|
|
|
|
@smallexample
|
|
int open2 (char *str1, char *str2, int flags, int mode)
|
|
@{
|
|
char name[strlen (str1) + strlen (str2) + 1];
|
|
stpcpy (stpcpy (name, str1), str2);
|
|
return open (name, flags, mode);
|
|
@}
|
|
@end smallexample
|
|
|
|
But @code{alloca} is not always equivalent to a variable-sized array, for
|
|
several reasons:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
A variable size array's space is freed at the end of the scope of the
|
|
name of the array. The space allocated with @code{alloca}
|
|
remains until the end of the function.
|
|
|
|
@item
|
|
It is possible to use @code{alloca} within a loop, allocating an
|
|
additional block on each iteration. This is impossible with
|
|
variable-sized arrays.
|
|
@end itemize
|
|
|
|
@strong{Note:} If you mix use of @code{alloca} and variable-sized arrays
|
|
within one function, exiting a scope in which a variable-sized array was
|
|
declared frees all blocks allocated with @code{alloca} during the
|
|
execution of that scope.
|
|
|
|
@ignore
|
|
@c This was never actually implemented. -zw
|
|
@node Relocating Allocator
|
|
@section Relocating Allocator
|
|
|
|
@cindex relocating memory allocator
|
|
Any system of dynamic memory allocation has overhead: the amount of
|
|
space it uses is more than the amount the program asks for. The
|
|
@dfn{relocating memory allocator} achieves very low overhead by moving
|
|
blocks in memory as necessary, on its own initiative.
|
|
|
|
@c @menu
|
|
@c * Relocator Concepts:: How to understand relocating allocation.
|
|
@c * Using Relocator:: Functions for relocating allocation.
|
|
@c @end menu
|
|
|
|
@node Relocator Concepts
|
|
@subsection Concepts of Relocating Allocation
|
|
|
|
@ifinfo
|
|
The @dfn{relocating memory allocator} achieves very low overhead by
|
|
moving blocks in memory as necessary, on its own initiative.
|
|
@end ifinfo
|
|
|
|
When you allocate a block with @code{malloc}, the address of the block
|
|
never changes unless you use @code{realloc} to change its size. Thus,
|
|
you can safely store the address in various places, temporarily or
|
|
permanently, as you like. This is not safe when you use the relocating
|
|
memory allocator, because any and all relocatable blocks can move
|
|
whenever you allocate memory in any fashion. Even calling @code{malloc}
|
|
or @code{realloc} can move the relocatable blocks.
|
|
|
|
@cindex handle
|
|
For each relocatable block, you must make a @dfn{handle}---a pointer
|
|
object in memory, designated to store the address of that block. The
|
|
relocating allocator knows where each block's handle is, and updates the
|
|
address stored there whenever it moves the block, so that the handle
|
|
always points to the block. Each time you access the contents of the
|
|
block, you should fetch its address anew from the handle.
|
|
|
|
To call any of the relocating allocator functions from a signal handler
|
|
is almost certainly incorrect, because the signal could happen at any
|
|
time and relocate all the blocks. The only way to make this safe is to
|
|
block the signal around any access to the contents of any relocatable
|
|
block---not a convenient mode of operation. @xref{Nonreentrancy}.
|
|
|
|
@node Using Relocator
|
|
@subsection Allocating and Freeing Relocatable Blocks
|
|
|
|
@pindex malloc.h
|
|
In the descriptions below, @var{handleptr} designates the address of the
|
|
handle. All the functions are declared in @file{malloc.h}; all are GNU
|
|
extensions.
|
|
|
|
@comment malloc.h
|
|
@comment GNU
|
|
@c @deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
|
|
This function allocates a relocatable block of size @var{size}. It
|
|
stores the block's address in @code{*@var{handleptr}} and returns
|
|
a non-null pointer to indicate success.
|
|
|
|
If @code{r_alloc} can't get the space needed, it stores a null pointer
|
|
in @code{*@var{handleptr}}, and returns a null pointer.
|
|
@end deftypefun
|
|
|
|
@comment malloc.h
|
|
@comment GNU
|
|
@c @deftypefun void r_alloc_free (void **@var{handleptr})
|
|
This function is the way to free a relocatable block. It frees the
|
|
block that @code{*@var{handleptr}} points to, and stores a null pointer
|
|
in @code{*@var{handleptr}} to show it doesn't point to an allocated
|
|
block any more.
|
|
@end deftypefun
|
|
|
|
@comment malloc.h
|
|
@comment GNU
|
|
@c @deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
|
|
The function @code{r_re_alloc} adjusts the size of the block that
|
|
@code{*@var{handleptr}} points to, making it @var{size} bytes long. It
|
|
stores the address of the resized block in @code{*@var{handleptr}} and
|
|
returns a non-null pointer to indicate success.
|
|
|
|
If enough memory is not available, this function returns a null pointer
|
|
and does not modify @code{*@var{handleptr}}.
|
|
@end deftypefun
|
|
@end ignore
|
|
|
|
@ignore
|
|
@comment No longer available...
|
|
|
|
@comment @node Memory Warnings
|
|
@comment @section Memory Usage Warnings
|
|
@comment @cindex memory usage warnings
|
|
@comment @cindex warnings of memory almost full
|
|
|
|
@pindex malloc.c
|
|
You can ask for warnings as the program approaches running out of memory
|
|
space, by calling @code{memory_warnings}. This tells @code{malloc} to
|
|
check memory usage every time it asks for more memory from the operating
|
|
system. This is a GNU extension declared in @file{malloc.h}.
|
|
|
|
@comment malloc.h
|
|
@comment GNU
|
|
@comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
|
|
Call this function to request warnings for nearing exhaustion of virtual
|
|
memory.
|
|
|
|
The argument @var{start} says where data space begins, in memory. The
|
|
allocator compares this against the last address used and against the
|
|
limit of data space, to determine the fraction of available memory in
|
|
use. If you supply zero for @var{start}, then a default value is used
|
|
which is right in most circumstances.
|
|
|
|
For @var{warn-func}, supply a function that @code{malloc} can call to
|
|
warn you. It is called with a string (a warning message) as argument.
|
|
Normally it ought to display the string for the user to read.
|
|
@end deftypefun
|
|
|
|
The warnings come when memory becomes 75% full, when it becomes 85%
|
|
full, and when it becomes 95% full. Above 95% you get another warning
|
|
each time memory usage increases.
|
|
|
|
@end ignore
|