libmpatrol.html

debug source code under unix platform.

forked.  If the <B>CHECKFORK</B> option is not used then a call to
<B>__mp_reinit</B> should be added as the first function call in the child
process in order to duplicate the behaviour of the <B>CHECKFORK</B> option.
<P>

Memory allocation profiling is supported, with statistics about every memory
allocation and deallocation that was made during the execution of a program
being written to a file at program termination if the <B>PROF</B> option is
used.  The information stored in this file can then be used by the <B>mprof</B>
command to display various tables summarising the memory allocation behaviour
of the program that produced it.  Memory allocation tracing is also supported,
where a trace of all memory allocations, reallocations and deallocations can be
written to a tracing output file in a concise encoded format for later
processing by the <B>mptrace</B> command.  This is controlled with the
<B>TRACE</B> option.
<A NAME="lbAE">&nbsp;</A>
<H2>FUNCTIONS</H2>

The following 19 functions are available as replacements for existing C library
functions.  To use these you must include <I>mpatrol.h</I> before all other
header files, although on UNIX and Windows platforms (and AmigaOS when using
<B>gcc</B>) they will be used anyway, albeit with slightly less tracing
information.  If <B>alloca</B> is being used and <I>alloca.h</I> is included then
<I>mpatrol.h</I> must appear after <I>alloca.h</I> otherwise the debugging version
of <B>alloca</B> will not be used:
<DL COMPACT>
<DT><B>malloc</B><DD>
Allocates <I>size</I> uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation.  The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
<I>size</I> bytes in length.  If <I>size</I> is <I>0</I> then the memory allocated
will be implicitly rounded up to <I>1</I> byte.  If there is not enough space in
the heap then the null pointer will be returned and <B>errno</B> will be set to
<B>ENOMEM</B>.  The allocated memory must be deallocated with <B>free</B> or
reallocated with <B>realloc</B>.
<DT><B>calloc</B><DD>
Allocates <I>nelem</I> elements of <I>size</I> zero-initialised bytes from the
heap and returns a pointer to the first byte of the allocation.  The pointer
returned will be suitably aligned for casting to any type and can be used to
store data of up to <I>nelem * size</I> bytes in length.  If <I>nelem * size</I>
is <I>0</I> then the amount of memory allocated will be implicitly rounded up to
<I>1</I> byte.  If there is not enough space in the heap then the null pointer
will be returned and <B>errno</B> will be set to <B>ENOMEM</B>.  The allocated
memory must be deallocated with <B>free</B> or reallocated with <B>realloc</B>.
<DT><B>memalign</B><DD>
Allocates <I>size</I> uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation.  The pointer returned will be aligned to
<I>align</I> bytes and can be used to store data of up to <I>size</I> bytes in
length.  If <I>align</I> is zero then the default system alignment will be used.
If <I>align</I> is not a power of two then it will be rounded up to the nearest
power of two.  If <I>align</I> is greater than the system page size then it will
be truncated to that value.  If <I>size</I> is <I>0</I> then the memory allocated
will be implicitly rounded up to <I>1</I> byte.  If there is not enough space in
the heap then the null pointer will be returned and <B>errno</B> will be set to
<B>ENOMEM</B>.  The allocated memory must be deallocated with <B>free</B> or
reallocated with <B>realloc</B>, although the latter will not guarantee the
preservation of alignment.
<DT><B>valloc</B><DD>
Allocates <I>size</I> uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation.  The pointer returned will be aligned to the
system page size and can be used to store data of up to <I>size</I> bytes in
length.  If <I>size</I> is <I>0</I> then the memory allocated will be implicitly
rounded up to <I>1</I> byte.  If there is not enough space in the heap then the
null pointer will be returned and <B>errno</B> will be set to <B>ENOMEM</B>.  The
allocated memory must be deallocated with <B>free</B> or reallocated with
<B>realloc</B>, although the latter will not guarantee the preservation of
alignment.
<DT><B>pvalloc</B><DD>
Allocates <I>size</I> uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation.  The pointer returned will be aligned to the
system page size and can be used to store data of up to <I>size</I> bytes in
length.  If <I>size</I> is <I>0</I> then the memory allocated will be implicitly
rounded up to <I>1</I> page, otherwise <I>size</I> will be implicitly rounded up
to a multiple of the system page size.  If there is not enough space in the heap
then the null pointer will be returned and <B>errno</B> will be set to
<B>ENOMEM</B>.  The allocated memory must be deallocated with <B>free</B> or
reallocated with <B>realloc</B>, although the latter will not guarantee the
preservation of alignment.
<DT><B>alloca</B><DD>
Allocates <I>size</I> temporary uninitialised bytes from the heap and returns a
pointer to the first byte of the allocation.  The pointer returned will be
suitably aligned for casting to any type and can be used to store data of up to
<I>size</I> bytes in length.  If <I>size</I> is <I>0</I> then the memory allocated
will be implicitly rounded up to <I>1</I> byte.  If there is not enough space in
the heap then the program will be terminated and the <I>OUTMEM</I> error will be
given.  The <B>alloca</B> function normally allocates its memory from the stack,
with the result that all such allocations will be freed when the function
returns.  This version of <B>alloca</B> allocates its memory from the heap in
order to provide better debugging, but the allocations may not necessarily be
freed immediately when the function returns.  The allocated memory can be
deallocated explicitly with <B>dealloca</B>, but may not be reallocated or
deallocated in any other way.  This function is available for backwards
compatibility with older C source code and should not be used in new code.
<DT><B>strdup</B><DD>
Allocates exactly enough memory from the heap to duplicate <I>str</I> (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying <I>str</I> to the newly-allocated memory.  The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of <I>str</I>.  If <I>str</I> is <B>NULL</B> then an error
will be given and the null pointer will be returned.  If there is not enough
space in the heap then the null pointer will be returned and <B>errno</B> will
be set to <B>ENOMEM</B>.  The allocated memory must be deallocated with
<B>free</B> or reallocated with <B>realloc</B>.
<DT><B>strndup</B><DD>
Allocates exactly enough memory from the heap to duplicate <I>str</I> (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying <I>str</I> to the newly-allocated memory.  The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of <I>str</I>.  If <I>str</I> is <B>NULL</B> and <I>size</I>
is non-zero then an error will be given and the null pointer will be returned.
If the length of <I>str</I> is greater than <I>size</I> then only <I>size</I>
characters will be allocated and copied, with one additional byte for the nul
character.  If there is not enough space in the heap then the null pointer will
be returned and <B>errno</B> will be set to <B>ENOMEM</B>.  The allocated memory
must be deallocated with <B>free</B> or reallocated with <B>realloc</B>.  This
function is available for backwards compatibility with older C libraries and
should not be used in new code.
<DT><B>strsave</B><DD>
Allocates exactly enough memory from the heap to duplicate <I>str</I> (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying <I>str</I> to the newly-allocated memory.  The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of <I>str</I>.  If <I>str</I> is <B>NULL</B> then an error
will be given and the null pointer will be returned.  If there is not enough
space in the heap then the null pointer will be returned and <B>errno</B> will
be set to <B>ENOMEM</B>.  The allocated memory must be deallocated with
<B>free</B> or reallocated with <B>realloc</B>.  This function is available for
backwards compatibility with older C libraries and should not be used in new
code.
<DT><B>strnsave</B><DD>
Allocates exactly enough memory from the heap to duplicate <I>str</I> (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying <I>str</I> to the newly-allocated memory.  The pointer
returned will have no alignment constraints and can be used to store character
data up to the length of <I>str</I>.  If <I>str</I> is <B>NULL</B> and <I>size</I>
is non-zero then an error will be given and the null pointer will be returned.
If the length of <I>str</I> is greater than <I>size</I> then only <I>size</I>
characters will be allocated and copied, with one additional byte for the nul
character.  If there is not enough space in the heap then the null pointer will
be returned and <B>errno</B> will be set to <B>ENOMEM</B>.  The allocated memory
must be deallocated with <B>free</B> or reallocated with <B>realloc</B>.  This
function is available for backwards compatibility with older C libraries and
should not be used in new code.
<DT><B>strdupa</B><DD>
Allocates exactly enough temporary memory from the heap to duplicate <I>str</I>
(including the terminating nul character) and returns a pointer to the first
byte of the allocation after copying <I>str</I> to the newly-allocated memory.
The pointer returned will have no alignment constraints and can be used to store
character data up to the length of <I>str</I>.  If <I>str</I> is <B>NULL</B> then
an error will be given and the null pointer will be returned.  If there is not
enough space in the heap then the program will be terminated and the
<I>OUTMEM</I> error will be given.  The <B>strdupa</B> function normally allocates
its memory from the stack, with the result that all such allocations will be
freed when the function returns.  This version of <B>strdupa</B> allocates its
memory from the heap in order to provide better debugging, but the allocations
may not necessarily be freed immediately when the function returns.  The
allocated memory can be deallocated explicitly with <B>dealloca</B>, but may not
be reallocated or deallocated in any other way.  This function is available for
backwards compatibility with older C source code and should not be used in new
code.
<DT><B>strndupa</B><DD>
Allocates exactly enough temporary memory from the heap to duplicate <I>str</I>
(including the terminating nul character) and returns a pointer to the first
byte of the allocation after copying <I>str</I> to the newly-allocated memory.
The pointer returned will have no alignment constraints and can be used to store
character data up to the length of <I>str</I>.  If <I>str</I> is <B>NULL</B> and
<I>size</I> is non-zero then an error will be given and the null pointer will be
returned.  If the length of <I>str</I> is greater than <I>size</I> then only
<I>size</I> characters will be allocated and copied, with one additional byte for
the nul character.  If there is not enough space in the heap then the program
will be terminated and the <I>OUTMEM</I> error will be given.  The <B>strndupa</B>
function normally allocates its memory from the stack, with the result that all
such allocations will be freed when the function returns.  This version of
<B>strndupa</B> allocates its memory from the heap in order to provide better
debugging, but the allocations may not necessarily be freed immediately when the
function returns.  The allocated memory can be deallocated explicitly with
<B>dealloca</B>, but may not be reallocated or deallocated in any other way.
This function is available for backwards compatibility with older C source code
and should not be used in new code.
<DT><B>realloc</B><DD>
Resizes the memory allocation beginning at <I>ptr</I> to <I>size</I> bytes and
returns a pointer to the first byte of the new allocation after copying
<I>ptr</I> to the newly-allocated memory, which will be truncated if <I>size</I>
is smaller than the original allocation.  The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
<I>size</I> bytes in length.  If <I>ptr</I> is <B>NULL</B> then the call will be
equivalent to <B>malloc</B>.  If <I>size</I> is <I>0</I> then the existing memory
allocation will be freed and the null pointer will be returned.  If <I>size</I>
is greater than the original allocation then the extra space will be filled with
uninitialised bytes.  If there is not enough space in the heap then the null
pointer will be returned and <B>errno</B> will be set to <B>ENOMEM</B>.  The
allocated memory must be deallocated with <B>free</B> and can be reallocated
again with <B>realloc</B>.
<DT><B>reallocf</B><DD>
Resizes the memory allocation beginning at <I>ptr</I> to <I>size</I> bytes and
returns a pointer to the first byte of the new allocation after copying
<I>ptr</I> to the newly-allocated memory, which will be truncated if <I>size</I>
is smaller than the original allocation.  The pointer returned will be suitably
aligned for casting to any type and can be used to store data of up to
<I>size</I> bytes in length.  If <I>ptr</I> is <B>NULL</B> then the call will be
equivalent to <B>malloc</B>.  If <I>size</I> is <I>0</I> then the existing memory
allocation will be freed and the null pointer will be returned.  If <I>size</I>
is greater than the original allocation then the extra space will be filled with
uninitialised bytes.  If there is not enough space in the heap then the null
pointer will be returned, the original allocation will be freed and <B>errno</B>
will be set to <B>ENOMEM</B>.  The allocated memory must be deallocated with
<B>free</B> and can be reallocated again with <B>realloc</B>.  This function is
available for backwards compatibility with older C libraries and should not be
used in new code.
<DT><B>recalloc</B><DD>
Resizes the memory allocation beginning at <I>ptr</I> to <I>nelem</I> elements of
<I>size</I> bytes and returns a pointer to the first byte of the new allocation
after copying <I>ptr</I> to the newly-allocated memory, which will be truncated