libmpatrol.3

debug source code under unix platform.

Searches up to \fIsize\fP bytes in \fIptr\fP for the first occurrence of
\fIbyte\fP and returns a pointer to it or \fBNULL\fP if no such byte occurs.  If
\fIsize\fP is \fB0\fP then no bytes will be searched.  If the operation would
affect an existing memory allocation in the heap but would straddle that
allocation's boundaries then an error message will be generated in the log file
and no bytes will be searched.
.TP
\fBmemmem\fP
Searches up to \fIsize1\fP bytes in \fIptr1\fP for the first occurrence of
\fIptr2\fP (which is exactly \fIsize2\fP bytes in length) and returns a pointer
to it or \fBNULL\fP if no such sequence of bytes occur.  If \fIsize1\fP or
\fIsize2\fP is \fB0\fP then no bytes will be searched.  If the operation would
affect an existing memory allocation in the heap but would straddle that
allocation's boundaries then an error message will be generated in the log file
and no bytes will be searched.
.PP
The following 42 functions are available as support routines for additional
control and tracing in the mpatrol library.  Although they are documented here
as being prefixed by \fB__mp_\fP, their equivalent functions that are prefixed
by \fBmpatrol_\fP are also defined as aliases in the \fImpatrol.h\fP header
file.  To use these you should include the \fImpatrol.h\fP header file:
.TP
\fB__mp_atexit\fP
Installs a function to be called when the mpatrol library terminates.  Up to 32
such functions can be registered and will be called in reverse order of
registration.  Returns \fI1\fP on success or \fP0\fP if \fIfunc\fP could not be
registered.
.TP
\fB__mp_setoption\fP
Sets the value of an mpatrol option after the library has been initialised.
Options that require values are listed in \fImpatrol.h\fP prefixed with
\fIMP_OPT_*\fP.  The \fIopt\fP argument should be set to one of these macros,
and the \fIval\fP argument should be set to the option value, cast to an
unsigned integer.  The return value will be \fI0\fP on success and \fI1\fP on
failure.  Options that are flags are listed in \fImpatrol.h\fP prefixed with
\fIMP_FLG_*\fP.  Multiple flags can be set or unset at once using the
\fIMP_OPT_SETFLAGS\fP and \fIMP_OPT_UNSETFLAGS\fP options respectively, with the
necessary flags specified in \fIval\fP.  The return value will be \fI0\fP on
success and a combination of all of the flags that could not be set or unset on
failure.
.TP
\fB__mp_getoption\fP
Gets the value of an mpatrol option after the library has been initialised.
If \fIopt\fP is a valid option listed in \fImpatrol.h\fP then \fI1\fP will be
returned and the associated value will be returned in \fIval\fP and cast to an
unsigned integer, otherwise \fI0\fP will be returned.  If \fIopt\fP is
\fIMP_OPT_SETFLAGS\fP then all of the mpatrol library flags that are set will be
returned in \fIval\fP.  If \fIopt\fP is \fIMP_OPT_UNSETFLAGS\fP then all of the
mpatrol library flags that are not set will be returned in \fIval\fP.
.TP
\fB__mp_libversion\fP
Returns the version number of the mpatrol library.  This can be useful for
verifying that the version of the mpatrol library that a program is linked with
is the one expected at compile-time.
.TP
\fB__mp_strerror\fP
Returns the error message corresponding to the error code \fIerr\fP or
\fBNULL\fP if no such error code exists.  The most recent error code recorded by
the mpatrol library can be obtained by examining \fB__mp_errno\fP.
.TP
\fB__mp_function\fP
Returns the name of the function corresponding to the allocation type \fIfunc\fP
or \fBNULL\fP if no such allocation type exists.
.TP
\fB__mp_setuser\fP
Sets the user data for the memory allocation containing \fIptr\fP.  The contents
of \fIdata\fP are entirely application-specific as user data will never be
examined by the mpatrol library.  Such data is associated with a memory
allocation for its entire lifetime unless overridden by a subsequent call to
\fB__mp_setuser\fP.  As such, the user data must be valid for the entire
lifetime of the memory allocation, perhaps even after the allocation has been
freed if the \fBNOFREE\fP option is being used.  This function returns \fI1\fP
if there is an allocated memory block containing \fIptr\fP, and \fI0\fP
otherwise.
.TP
\fB__mp_setmark\fP
Sets the marked flag for the memory allocation containing \fIptr\fP, indicating
that the memory allocation cannot be freed (but can be reallocated) and thus
will not be listed as a memory leak.  This function returns \fI1\fP if there is
an allocated memory block containing \fIptr\fP, and \fI0\fP otherwise.  Note
that a memory allocation made by \fBalloca\fP, \fBstrdupa\fP or \fBstrndupa\fP
may not be marked.
.TP
\fB__mp_info\fP
Obtains information about a specific memory allocation by placing statistics
about \fIptr\fP in \fIinfo\fP.  If \fIptr\fP does not belong to a previously
allocated memory allocation or free memory block then \fI0\fP will be returned,
otherwise \fI1\fP will be returned and \fIinfo\fP will contain the following
information (note that a free memory block will only contain the \fIblock\fP and
\fIsize\fP fields and can be identified by not having the \fIallocated\fP flag
set):

.TS
l l.
\fBField\fP	\fBDescription\fP

\fBblock\fP	Pointer to first byte of alloc.
\fBsize\fP	Size of alloc in bytes.
\fBtype\fP	Type of function which allocated memory.
\fBalloc\fP	Allocation index.
\fBrealloc\fP	Number of times reallocated.
\fBthread\fP	Thread identifier.
\fBevent\fP	Event of last modification.
\fBfunc\fP	Function in which alloc took place.
\fBfile\fP	File in which alloc took place.
\fBline\fP	Line number at which alloc took place.
\fBstack\fP	Pointer to function call stack.
\fBtypestr\fP	Type stored in allocation.
\fBtypesize\fP	Size of type stored in allocation.
\fBuserdata\fP	User data associated with allocation.
\fBallocated\fP	Indicates if alloc was allocated.
\fBfreed\fP	Indicates if alloc has been freed.
\fBmarked\fP	Indicates if alloc has been marked.
\fBprofiled\fP	Indicates if alloc has been profiled.
\fBtraced\fP	Indicates if alloc has been traced.
\fBinternal\fP	Indicates if alloc is internal.
.TE
.TP
\fB__mp_syminfo\fP
Obtains symbolic information about a specific code address by placing statistics
about \fIptr\fP in \fIinfo\fP.  If \fIptr\fP does not belong to a function
symbol then \fI0\fP will be returned, otherwise \fI1\fP will be returned and
\fIinfo\fP will contain the following information:

.TS
l l.
\fBField\fP	\fBDescription\fP

\fBname\fP	Name of symbol.
\fBobject\fP	File containing symbol.
\fBaddr\fP	Start address of symbol.
\fBsize\fP	Size of symbol.
\fBfile\fP	Filename corresponding to address.
\fBline\fP	Line number corresponding to address.
.TE
.TP
\fB__mp_symbol\fP
Obtains the name of a function symbol containing the code address specified in
\fIptr\fP.  If \fIptr\fP does not belong to a function symbol then \fBNULL\fP
will be returned.
.TP
\fB__mp_printinfo\fP
Displays information about a specific memory allocation containing \fIptr\fP to
the standard error file stream.  If \fIptr\fP does not belong to a previously
allocated memory allocation or free memory block then \fI0\fP will be returned,
otherwise \fI1\fP will be returned.  This function is intended to be called from
within a debugger.
.TP
\fB__mp_snapshot\fP
Returns the current event number, effectively taking a snapshot of the heap.
This number can then be used in later calls to \fB__mp_iterate\fP.
.TP
\fB__mp_iterate\fP
Iterates over all of the current allocated and freed memory allocations,
calling \fIfunc\fP with the start address of every memory allocation that has
been modified since event number \fIevent\fP.  If \fIfunc\fP is \fBNULL\fP then
\fB__mp_printinfo\fP will be used as the callback function.  If \fBevent\fP is
\fI0\fP then \fIfunc\fP will be called with the start address of every memory
allocation.  If \fIfunc\fP returns a negative number then the iteration process
will be stopped immediately.  If \fIfunc\fP returns a positive number above zero
then \fB__mp_iterate\fP will return the number of times \fIfunc\fP returned a
non-zero number after the iteration process has stopped.  The \fIdata\fP
argument is passed directly to \fIfunc\fP as its second argument and is not
read by the mpatrol library.
.TP
\fB__mp_iterateall\fP
Iterates over all of the current allocated and freed memory allocations and any
free memory blocks, calling \fIfunc\fP with the start address of every memory
allocation or free block.  If \fIfunc\fP is \fBNULL\fP then \fB__mp_printinfo\fP
will be used as the callback function.  If \fIfunc\fP returns a negative number
then the iteration process will be stopped immediately.  If \fIfunc\fP returns a
positive number above zero then \fB__mp_iterate\fP will return the number of
times \fIfunc\fP returned a non-zero number after the iteration process has
stopped.  The \fIdata\fP argument is passed directly to \fIfunc\fP as its second
argument and is not read by the mpatrol library.  Note that unlike
\fB__mp_iterate\fP, this function will also include internal memory allocations
made by the mpatrol library and is intended for walking the entire heap.
.TP
\fB__mp_addallocentry\fP
Adds an entry representing an allocation of size \fIsize\fP to the leak table.
The allocation will be associated with a source filename of \fIfile\fP and a
line number of \fIline\fP if the former is non-\fBNULL\fP and the latter is
non-zero.  If \fIfile\fP is non-\fBNULL\fP and \fIline\fP is \fI0\fP then
\fIfile\fP represents the name of the function that made the allocation.  If
\fIfile\fP is \fBNULL\fP and \fIline\fP is non-zero then \fIline\fP represents
the code address at which the allocation was made.  If \fIfile\fP is \fBNULL\fP
and \fIline\fP is \fI0\fP then the location of the allocation is unknown.
Returns \fI1\fP on success and \fI0\fP if there was no more memory available to
add another entry to the leak table.
.TP
\fB__mp_addfreeentry\fP
Adds an entry representing a deallocation of size \fIsize\fP to the leak table.
The deallocation will be associated with a source filename of \fIfile\fP and a
line number of \fIline\fP if the former is non-\fBNULL\fP and the latter is
non-zero.  If \fIfile\fP is non-\fBNULL\fP and \fIline\fP is \fI0\fP then
\fIfile\fP represents the name of the function that made the deallocation.  If
\fIfile\fP is \fBNULL\fP and \fIline\fP is non-zero then \fIline\fP represents
the code address at which the deallocation was made.  If \fIfile\fP is
\fBNULL\fP and \fIline\fP is \fI0\fP then the location of the deallocation is
unknown.  Returns \fI1\fP on success and \fI0\fP if there was no existing
allocation from the same location in the leak table.
.TP
\fB__mp_clearleaktable\fP
Deletes all of the existing entries in the leak table, making it empty.  This
will also affect the behaviour of the \fBLEAKTABLE\fP option since that option
will then only be able to show a summary of the entries in the leak table that
were collected after the last call to this function rather than from the start
of program execution.
.TP
\fB__mp_startleaktable\fP
Starts the automatic logging of all memory allocations, reallocations and
deallocations to the leak table.  Returns \fI1\fP if such logging was already
being performed and \fI0\fP otherwise.
.TP
\fB__mp_stopleaktable\fP
Stops the automatic logging of all memory allocations, reallocations and
deallocations to the leak table.  Returns \fI1\fP if such logging was already
being performed and \fI0\fP otherwise.
.TP
\fB__mp_leaktable\fP
Displays a summary of up to \fIsize\fP entries from the leak table, or all
entries if \fIsize\fP is \fI0\fP.  If \fIopt\fP is \fIMP_LT_ALLOCATED\fP then
all allocated entries will be displayed, if \fIopt\fP is \fIMP_LT_FREED\fP then
all freed entries will be displayed and if \fIopt\fP is \fIMP_LT_UNFREED\fP then
all unfreed entries will be displayed.  The summary is normally sorted in
descending order of total bytes from each entry, but this can be changed by
setting \fIflags\fP to any combination of \fIMP_LT_COUNTS\fP (to sort by the
number of occurrences in each entry) and \fIMP_LT_BOTTOM\fP (to sort in
ascending order).
.TP
\fB__mp_memorymap\fP
If \fIstats\fP is non-zero then the current statistics of the mpatrol library
will be displayed.  If the heap contains at least one allocated, freed or free
block then a map of the current heap will also be displayed.
.TP
\fB__mp_summary\fP
Displays information about the current state of the mpatrol library, including
its settings and any relevant statistics.
.TP
\fB__mp_stats\fP
Obtains statistics about the current state of the heap and places them in
\fIinfo\fP.  If this information could not be determined then \fI0\fP will be
returned, otherwise \fI1\fP will be returned and \fIinfo\fP will contain the