libmpatrol.3

debug source code under unix platform.

functions will then be called as soon as the mpatrol library is initialised,
which can be useful if the initialisation occurs before \fBmain\fP is called.
These functions must accept no arguments and must return no value.  Similar
behaviour exists for global functions whose names begin with \fB__mp_fini_\fP,
except that such functions will be executed when the mpatrol library terminates.
Note that this feature will have no effect if the symbol table is stripped from
the executable file or shared library before the program is run, and the order
in which such functions will be called if there are more than one is
unspecified.
.PP
On UNIX platforms, the \fBfork\fP function can cause problems if it is used
to make a copy of the parent process without immediately calling one of the
\fBexec\fP family of functions.  This is because the child process inherits
all of the memory allocations of the parent process, but also inherits the log,
profile and trace files as well.  If both the parent and child processes make
subsequent memory allocations there will be multiple entries with the same
allocation indices written to the log, profile or trace files.  This can be
most confusing when processing these files afterwards!  As a workaround, the
mpatrol library will always check the current process identifier every time one
of its functions is called if the \fBCHECKFORK\fP option is used and will open
new log, profile or trace files if it has determined that the process has been
forked.  If the \fBCHECKFORK\fP option is not used then a call to
\fB__mp_reinit\fP should be added as the first function call in the child
process in order to duplicate the behaviour of the \fBCHECKFORK\fP option.
.PP
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 \fBPROF\fP option is
used.  The information stored in this file can then be used by the \fBmprof\fP
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 \fBmptrace\fP command.  This is controlled with the
\fBTRACE\fP option.
.SH FUNCTIONS
The following 19 functions are available as replacements for existing C library
functions.  To use these you must include \fImpatrol.h\fP before all other
header files, although on UNIX and Windows platforms (and AmigaOS when using
\fBgcc\fP) they will be used anyway, albeit with slightly less tracing
information.  If \fBalloca\fP is being used and \fIalloca.h\fP is included then
\fImpatrol.h\fP must appear after \fIalloca.h\fP otherwise the debugging version
of \fBalloca\fP will not be used:
.TP
\fBmalloc\fP
Allocates \fIsize\fP 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
\fIsize\fP bytes in length.  If \fIsize\fP is \fI0\fP then the memory allocated
will be implicitly rounded up to \fI1\fP byte.  If there is not enough space in
the heap then the null pointer will be returned and \fBerrno\fP will be set to
\fBENOMEM\fP.  The allocated memory must be deallocated with \fBfree\fP or
reallocated with \fBrealloc\fP.
.TP
\fBcalloc\fP
Allocates \fInelem\fP elements of \fIsize\fP 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 \fInelem * size\fP bytes in length.  If \fInelem * size\fP
is \fI0\fP then the amount of memory allocated will be implicitly rounded up to
\fI1\fP byte.  If there is not enough space in the heap then the null pointer
will be returned and \fBerrno\fP will be set to \fBENOMEM\fP.  The allocated
memory must be deallocated with \fBfree\fP or reallocated with \fBrealloc\fP.
.TP
\fBmemalign\fP
Allocates \fIsize\fP uninitialised bytes from the heap and returns a pointer to
the first byte of the allocation.  The pointer returned will be aligned to
\fIalign\fP bytes and can be used to store data of up to \fIsize\fP bytes in
length.  If \fIalign\fP is zero then the default system alignment will be used.
If \fIalign\fP is not a power of two then it will be rounded up to the nearest
power of two.  If \fIalign\fP is greater than the system page size then it will
be truncated to that value.  If \fIsize\fP is \fI0\fP then the memory allocated
will be implicitly rounded up to \fI1\fP byte.  If there is not enough space in
the heap then the null pointer will be returned and \fBerrno\fP will be set to
\fBENOMEM\fP.  The allocated memory must be deallocated with \fBfree\fP or
reallocated with \fBrealloc\fP, although the latter will not guarantee the
preservation of alignment.
.TP
\fBvalloc\fP
Allocates \fIsize\fP 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 \fIsize\fP bytes in
length.  If \fIsize\fP is \fI0\fP then the memory allocated will be implicitly
rounded up to \fI1\fP byte.  If there is not enough space in the heap then the
null pointer will be returned and \fBerrno\fP will be set to \fBENOMEM\fP.  The
allocated memory must be deallocated with \fBfree\fP or reallocated with
\fBrealloc\fP, although the latter will not guarantee the preservation of
alignment.
.TP
\fBpvalloc\fP
Allocates \fIsize\fP 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 \fIsize\fP bytes in
length.  If \fIsize\fP is \fI0\fP then the memory allocated will be implicitly
rounded up to \fI1\fP page, otherwise \fIsize\fP 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 \fBerrno\fP will be set to
\fBENOMEM\fP.  The allocated memory must be deallocated with \fBfree\fP or
reallocated with \fBrealloc\fP, although the latter will not guarantee the
preservation of alignment.
.TP
\fBalloca\fP
Allocates \fIsize\fP 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
\fIsize\fP bytes in length.  If \fIsize\fP is \fI0\fP then the memory allocated
will be implicitly rounded up to \fI1\fP byte.  If there is not enough space in
the heap then the program will be terminated and the \fIOUTMEM\fP error will be
given.  The \fBalloca\fP 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 \fBalloca\fP 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 \fBdealloca\fP, 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.
.TP
\fBstrdup\fP
Allocates exactly enough memory from the heap to duplicate \fIstr\fP (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP 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 \fBerrno\fP will
be set to \fBENOMEM\fP.  The allocated memory must be deallocated with
\fBfree\fP or reallocated with \fBrealloc\fP.
.TP
\fBstrndup\fP
Allocates exactly enough memory from the heap to duplicate \fIstr\fP (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP and \fIsize\fP
is non-zero then an error will be given and the null pointer will be returned.
If the length of \fIstr\fP is greater than \fIsize\fP then only \fIsize\fP
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 \fBerrno\fP will be set to \fBENOMEM\fP.  The allocated memory
must be deallocated with \fBfree\fP or reallocated with \fBrealloc\fP.  This
function is available for backwards compatibility with older C libraries and
should not be used in new code.
.TP
\fBstrsave\fP
Allocates exactly enough memory from the heap to duplicate \fIstr\fP (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP 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 \fBerrno\fP will
be set to \fBENOMEM\fP.  The allocated memory must be deallocated with
\fBfree\fP or reallocated with \fBrealloc\fP.  This function is available for
backwards compatibility with older C libraries and should not be used in new
code.
.TP
\fBstrnsave\fP
Allocates exactly enough memory from the heap to duplicate \fIstr\fP (including
the terminating nul character) and returns a pointer to the first byte of the
allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP and \fIsize\fP
is non-zero then an error will be given and the null pointer will be returned.
If the length of \fIstr\fP is greater than \fIsize\fP then only \fIsize\fP
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 \fBerrno\fP will be set to \fBENOMEM\fP.  The allocated memory
must be deallocated with \fBfree\fP or reallocated with \fBrealloc\fP.  This
function is available for backwards compatibility with older C libraries and
should not be used in new code.
.TP
\fBstrdupa\fP
Allocates exactly enough temporary memory from the heap to duplicate \fIstr\fP
(including the terminating nul character) and returns a pointer to the first
byte of the allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP 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
\fIOUTMEM\fP error will be given.  The \fBstrdupa\fP 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 \fBstrdupa\fP 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 \fBdealloca\fP, 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.
.TP
\fBstrndupa\fP
Allocates exactly enough temporary memory from the heap to duplicate \fIstr\fP
(including the terminating nul character) and returns a pointer to the first
byte of the allocation after copying \fIstr\fP 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 \fIstr\fP.  If \fIstr\fP is \fBNULL\fP and
\fIsize\fP is non-zero then an error will be given and the null pointer will be
returned.  If the length of \fIstr\fP is greater than \fIsize\fP then only
\fIsize\fP 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 \fIOUTMEM\fP error will be given.  The \fBstrndupa\fP
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
\fBstrndupa\fP 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
\fBdealloca\fP, 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.
.TP
\fBrealloc\fP
Resizes the memory allocation beginning at \fIptr\fP to \fIsize\fP bytes and
returns a pointer to the first byte of the new allocation after copying
\fIptr\fP to the newly-allocated memory, which will be truncated if \fIsize\fP
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
\fIsize\fP bytes in length.  If \fIptr\fP is \fBNULL\fP then the call will be
equivalent to \fBmalloc\fP.  If \fIsize\fP is \fI0\fP then the existing memory
allocation will be freed and the null pointer will be returned.  If \fIsize\fP
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 \fBerrno\fP will be set to \fBENOMEM\fP.  The
allocated memory must be deallocated with \fBfree\fP and can be reallocated
again with \fBrealloc\fP.
.TP
\fBreallocf\fP
Resizes the memory allocation beginning at \fIptr\fP to \fIsize\fP bytes and
returns a pointer to the first byte of the new allocation after copying
\fIptr\fP to the newly-allocated memory, which will be truncated if \fIsize\fP
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
\fIsize\fP bytes in length.  If \fIptr\fP is \fBNULL\fP then the call will be
equivalent to \fBmalloc\fP.  If \fIsize\fP is \fI0\fP then the existing memory
allocation will be freed and the null pointer will be returned.  If \fIsize\fP
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 \fBerrno\fP
will be set to \fBENOMEM\fP.  The allocated memory must be deallocated with
\fBfree\fP and can be reallocated again with \fBrealloc\fP.  This function is
available for backwards compatibility with older C libraries and should not be
used in new code.
.TP
\fBrecalloc\fP
Resizes the memory allocation beginning at \fIptr\fP to \fInelem\fP elements of