libmpatrol.html

debug source code under unix platform.

being performed and <I>0</I> otherwise.
<DT><B>__mp_leaktable</B><DD>
Displays a summary of up to <I>size</I> entries from the leak table, or all
entries if <I>size</I> is <I>0</I>.  If <I>opt</I> is <I>MP_LT_ALLOCATED</I> then
all allocated entries will be displayed, if <I>opt</I> is <I>MP_LT_FREED</I> then
all freed entries will be displayed and if <I>opt</I> is <I>MP_LT_UNFREED</I> 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 <I>flags</I> to any combination of <I>MP_LT_COUNTS</I> (to sort by the
number of occurrences in each entry) and <I>MP_LT_BOTTOM</I> (to sort in
ascending order).
<DT><B>__mp_memorymap</B><DD>
If <I>stats</I> 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.
<DT><B>__mp_summary</B><DD>
Displays information about the current state of the mpatrol library, including
its settings and any relevant statistics.
<DT><B>__mp_stats</B><DD>
Obtains statistics about the current state of the heap and places them in
<I>info</I>.  If this information could not be determined then <I>0</I> will be
returned, otherwise <I>1</I> will be returned and <I>info</I> will contain the
following information:
<P>
<TABLE>
<TR VALIGN=top><TD><B>Field</B></TD><TD><B>Description</B><BR></TD></TR>
<TR VALIGN=top><TD></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD><B>acount</B></TD><TD>Total number of allocated blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>atotal</B></TD><TD>Total size of allocated blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>fcount</B></TD><TD>Total number of free blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>ftotal</B></TD><TD>Total size of free blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>gcount</B></TD><TD>Total number of freed blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>gtotal</B></TD><TD>Total size of freed blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>icount</B></TD><TD>Total number of internal blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>itotal</B></TD><TD>Total size of internal blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>mcount</B></TD><TD>Total number of marked blocks.<BR></TD></TR>
<TR VALIGN=top><TD><B>mtotal</B></TD><TD>Total size of marked blocks.<BR></TD></TR>
</TABLE>

<DT><B>__mp_check</B><DD>
Forces the library to perform an immediate check of the overflow buffers of
every memory allocation and to ensure that nothing has overwritten any free
blocks.  If any memory allocations made by the <B>alloca</B> family of functions
are out of scope then this function will also cause them to be freed.
<DT><B>__mp_prologue</B><DD>
Installs a prologue function to be called before any memory allocation,
reallocation or deallocation function.  This function will return a pointer to
the previously installed prologue function, or the null pointer if no prologue
function had been previously installed.  The following arguments will be used
to call the prologue function (the last four arguments contain the function
name, file name, line number and the return address of the calling function, or
null pointers and zero if they cannot be determined):
<P>
<TABLE>
<TR VALIGN=top><TD ALIGN=center><B>Argument 1</B></TD><TD ALIGN=center><B>Argument 2</B></TD><TD ALIGN=center><B>Argument 3</B></TD><TD><B>Called by</B><BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center></TD><TD ALIGN=center></TD><TD ALIGN=center></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center><I>-1</I></TD><TD ALIGN=center><I>size</I></TD><TD ALIGN=center><I>align</I></TD><TD><B>malloc</B>, etc.<BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center><I>ptr</I></TD><TD ALIGN=center><I>size</I></TD><TD ALIGN=center><I>align</I></TD><TD><B>realloc</B>, etc.<BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center><I>ptr</I></TD><TD ALIGN=center><I>-1</I></TD><TD ALIGN=center><I>0</I></TD><TD><B>free</B>, etc.<BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center><I>ptr</I></TD><TD ALIGN=center><I>-2</I></TD><TD ALIGN=center><I>1</I></TD><TD><B>strdup</B>, etc.<BR></TD></TR>
</TABLE>

<DT><B>__mp_epilogue</B><DD>
Installs an epilogue function to be called after any memory allocation,
reallocation or deallocation function.  This function will return a pointer to
the previously installed epilogue function, or the null pointer if no epilogue
function had been previously installed.  The following arguments will be used
to call the epilogue function (the last four arguments contain the function
name, file name, line number and the return address of the calling function, or
null pointers and zero if they cannot be determined):
<P>
<TABLE>
<TR VALIGN=top><TD ALIGN=center><B>Argument</B></TD><TD><B>Called by</B><BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center><I>ptr</I></TD><TD><B>malloc</B>, <B>realloc</B>, <B>strdup</B>, etc.<BR></TD></TR>
<TR VALIGN=top><TD ALIGN=center><I>-1</I></TD><TD><B>free</B>, etc.<BR></TD></TR>
</TABLE>

<DT><B>__mp_nomemory</B><DD>
Installs a low-memory handler and returns a pointer to the previously installed
handler, or the null pointer if no handler had been previously installed.  This
will be called once by C memory allocation functions, and repeatedly by C++
memory allocation functions, when they would normally return <B>NULL</B>.  The
four arguments contain the function name, file name, line number and the return
address of the calling function, or null pointers and zero if they cannot be
determined.  Note that this function is equivalent to <B>set_new_handler</B> and
will replace the handler installed by that function.
<DT><B>__mp_printf</B><DD>
Writes format string <I>fmt</I> with variable arguments to the log file, with
each line prefixed by <I>&gt;</I>.  The final length of the string that is written
to the log file must not exceed 1024 characters.  Returns the number of
characters written, or a negative number upon error.
<DT><B>__mp_vprintf</B><DD>
Writes format string <I>fmt</I> with variable argument list <I>args</I> to the log
file, with each line prefixed by <I>&gt;</I>.  The final length of the string that
is written to the log file must not exceed 1024 characters.  Returns the number
of characters written, or a negative number upon error.
<DT><B>__mp_locprintf</B><DD>
Writes format string <I>fmt</I> with variable arguments to the log file, with
each line prefixed by <I>&gt;</I>.  The final length of the string that is written
to the log file must not exceed 1024 characters.  It also writes information to
the log file about where the call to this function was made, which includes the
source file location and the call stack if they are available.
<DT><B>__mp_vlocprintf</B><DD>
Writes format string <I>fmt</I> with variable argument list <I>args</I> to the log
file, with each line prefixed by <I>&gt;</I>.  The final length of the string that
is written to the log file must not exceed 1024 characters.  It also writes
information to the log file about where the call to this function was made,
which includes the source file location and the call stack if they are
available.
<DT><B>__mp_logmemory</B><DD>
Displays the contents of a block of memory beginning at <I>ptr</I>, dumping
<I>size</I> consecutive bytes to the log file in hexadecimal format.
<DT><B>__mp_logstack</B><DD>
Displays the current call stack, skipping <I>frames</I> stack frames from the
current stack frame before writing the symbolic stack trace to the log file.
Returns <I>1</I> if successful, or <I>0</I> if the call stack could not be
determined or if <I>frames</I> was too large for the current call stack.
<DT><B>__mp_logaddr</B><DD>
Displays information about a specific memory allocation containing <I>ptr</I> to
the log file.  If <I>ptr</I> does not belong to a previously allocated memory
allocation then <I>0</I> will be returned, otherwise <I>1</I> will be returned.
<DT><B>__mp_edit</B><DD>
Invokes a text editor to edit <I>file</I> at line number <I>line</I> via the
<B>mpedit</B> command.  Returns <I>1</I> if the text editor was successfully
invoked, <I>-1</I> if there was an error, or <I>0</I> if there is no support for
this feature.  This function will only work on a system where the <B>EDIT</B>
option works.
<DT><B>__mp_list</B><DD>
Displays a context listing of <I>file</I> at line number <I>line</I> via the
<B>mpedit</B> command.  Returns <I>1</I> if the listing was successfully
performed, <I>-1</I> if there was an error, or <I>0</I> if there is no support for
this feature.  This function will only work on a system where the <B>LIST</B>
option works.
<DT><B>__mp_view</B><DD>
Either invokes a text editor to edit <I>file</I> at line number <I>line</I> or
displays a context listing of <I>file</I> at line number <I>line</I> depending
on the setting of the <B>EDIT</B> and <B>LIST</B> options.  This is done via the
<B>mpedit</B> command and will have no effect if the <B>EDIT</B> and <B>LIST</B>
options are not set or if these options are not supported on the system.
Returns <I>1</I> if the edit or listing was successfully performed, <I>-1</I> if
there was an error, or <I>0</I> if neither of the options were set or if there is
no support for this feature.
<DT><B>__mp_readcontents</B><DD>
Reads the contents of a memory allocation contents file into the memory
allocation containing <I>ptr</I>.  The name of the file is composed of the
<I>file</I> string followed by the allocation index of the memory allocation
separated by a dot.  If <I>file</I> is <B>NULL</B> then it is assumed to be
<I>.mpatrol</I>.  Returns <I>1</I> if the contents were read successfully and
<I>0</I> otherwise.
<DT><B>__mp_writecontents</B><DD>
Writes the contents of the memory allocation containing <I>ptr</I> to an
allocation contents file.  The name of the file is composed of the <I>file</I>
string followed by the allocation index of the memory allocation separated by
a dot.  If <I>file</I> is <B>NULL</B> then it is assumed to be <I>.mpatrol</I>.
Returns <I>1</I> if the contents were written successfully and <I>0</I> otherwise.
<DT><B>__mp_cmpcontents</B><DD>
Compares the contents of the memory allocation containing <I>ptr</I> with the
contents of a previously written allocation contents file.  The name of the file
is composed of the <I>file</I> string followed by the allocation index of the
memory allocation separated by a dot.  If <I>file</I> is <B>NULL</B> then it is
assumed to be <I>.mpatrol</I>.  Any differences are written to the mpatrol log
file.  Returns the number of differences found, or <I>-1</I> if there was an
error.
<DT><B>__mp_remcontents</B><DD>
Removes the memory allocation contents file that corresponds to the memory
allocation containing <I>ptr</I>.  The name of the file is composed of the
<I>file</I> string followed by the allocation index of the memory allocation
separated by a dot.  If <I>file</I> is <B>NULL</B> then it is assumed to be
<I>.mpatrol</I>.  Returns <I>1</I> if the file was removed successfully and
<I>0</I> otherwise.
</DL>
<P>

The following global variable is available for additional control in the mpatrol
library.  To use it you should include the <I>mpatrol.h</I> header file:
<DL COMPACT>
<DT><B>__mp_errno</B><DD>
Contains the most recent error code encountered by the mpatrol library.  Its
value can be reset to <I>MP_ET_NONE</I> before calling an mpatrol library
function, and then examined afterwards, either by comparison with the known
error codes in the <I>__mp_errortype</I> enumeration, or with
<B>__mp_strerror</B>.
</DL>
<A NAME="lbAF">&nbsp;</A>
<H2>LINKING</H2>

In order to use the mpatrol library on UNIX platforms, the following libraries
must be linked in before any other library that defines dynamic memory
allocation functions with the same names:
<P>
<TABLE>
<TR VALIGN=top><TD><B>Library</B></TD><TD><B>Reason</B><BR></TD></TR>
<TR VALIGN=top><TD></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD><I>-lmpatrol</I></TD><TD>To use this library.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lmpatrolmt</I></TD><TD>To use the thread-safe mpatrol library.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lmpalloc</I></TD><TD>To use the release library.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lmptools</I></TD><TD>To use the mpatrol tools library.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lld</I></TD><TD>If built with COFF or XCOFF support.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lelf</I></TD><TD>If built with ELF support.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lbfd</I> &amp; <I>-liberty</I></TD><TD>If built with BFD support.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lcl</I></TD><TD>If built on HP/UX.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lexc</I></TD><TD>If built on IRIX or Tru64.<BR></TD></TR>
<TR VALIGN=top><TD><I>-limagehlp</I></TD><TD>If built on Windows.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lpthreads</I></TD><TD>If built on AIX with threads support.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lthread</I></TD><TD>If built on DG/UX with threads support.<BR></TD></TR>
<TR VALIGN=top><TD><I>-lpthread</I></TD><TD>If built on UNIX with threads support.<BR></TD></TR>
</TABLE>

<P>

On UNIX pla