libmpatrol.html

debug source code under unix platform.

<I>ptr2</I> then no bytes will be compared.  If the operation would read from 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 compared.
<DT><B>bcmp</B><DD>
Compares <I>size</I> bytes from <I>ptr1</I> and <I>ptr2</I> and returns <B>0</B> if
all of the bytes are identical, or returns the byte difference of the first
differing bytes.  If <I>size</I> is <B>0</B> or <I>ptr1</I> is the same as
<I>ptr2</I> then no bytes will be compared.  If the operation would read from 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 compared.  This function is available for backwards compatibility with
older C libraries and should not be used in new code.
<DT><B>memchr</B><DD>
Searches up to <I>size</I> bytes in <I>ptr</I> for the first occurrence of
<I>byte</I> and returns a pointer to it or <B>NULL</B> if no such byte occurs.  If
<I>size</I> is <B>0</B> 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.
<DT><B>memmem</B><DD>
Searches up to <I>size1</I> bytes in <I>ptr1</I> for the first occurrence of
<I>ptr2</I> (which is exactly <I>size2</I> bytes in length) and returns a pointer
to it or <B>NULL</B> if no such sequence of bytes occur.  If <I>size1</I> or
<I>size2</I> is <B>0</B> 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.
</DL>
<P>

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 <B>__mp_</B>, their equivalent functions that are prefixed
by <B>mpatrol_</B> are also defined as aliases in the <I>mpatrol.h</I> header
file.  To use these you should include the <I>mpatrol.h</I> header file:
<DL COMPACT>
<DT><B>__mp_atexit</B><DD>
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 <I>1</I> on success or 0 if <I>func</I> could not be
registered.
<DT><B>__mp_setoption</B><DD>
Sets the value of an mpatrol option after the library has been initialised.
Options that require values are listed in <I>mpatrol.h</I> prefixed with
<I>MP_OPT_*</I>.  The <I>opt</I> argument should be set to one of these macros,
and the <I>val</I> argument should be set to the option value, cast to an
unsigned integer.  The return value will be <I>0</I> on success and <I>1</I> on
failure.  Options that are flags are listed in <I>mpatrol.h</I> prefixed with
<I>MP_FLG_*</I>.  Multiple flags can be set or unset at once using the
<I>MP_OPT_SETFLAGS</I> and <I>MP_OPT_UNSETFLAGS</I> options respectively, with the
necessary flags specified in <I>val</I>.  The return value will be <I>0</I> on
success and a combination of all of the flags that could not be set or unset on
failure.
<DT><B>__mp_getoption</B><DD>
Gets the value of an mpatrol option after the library has been initialised.
If <I>opt</I> is a valid option listed in <I>mpatrol.h</I> then <I>1</I> will be
returned and the associated value will be returned in <I>val</I> and cast to an
unsigned integer, otherwise <I>0</I> will be returned.  If <I>opt</I> is
<I>MP_OPT_SETFLAGS</I> then all of the mpatrol library flags that are set will be
returned in <I>val</I>.  If <I>opt</I> is <I>MP_OPT_UNSETFLAGS</I> then all of the
mpatrol library flags that are not set will be returned in <I>val</I>.
<DT><B>__mp_libversion</B><DD>
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.
<DT><B>__mp_strerror</B><DD>
Returns the error message corresponding to the error code <I>err</I> or
<B>NULL</B> if no such error code exists.  The most recent error code recorded by
the mpatrol library can be obtained by examining <B>__mp_errno</B>.
<DT><B>__mp_function</B><DD>
Returns the name of the function corresponding to the allocation type <I>func</I>
or <B>NULL</B> if no such allocation type exists.
<DT><B>__mp_setuser</B><DD>
Sets the user data for the memory allocation containing <I>ptr</I>.  The contents
of <I>data</I> 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
<B>__mp_setuser</B>.  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 <B>NOFREE</B> option is being used.  This function returns <I>1</I>
if there is an allocated memory block containing <I>ptr</I>, and <I>0</I>
otherwise.
<DT><B>__mp_setmark</B><DD>
Sets the marked flag for the memory allocation containing <I>ptr</I>, 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 <I>1</I> if there is
an allocated memory block containing <I>ptr</I>, and <I>0</I> otherwise.  Note
that a memory allocation made by <B>alloca</B>, <B>strdupa</B> or <B>strndupa</B>
may not be marked.
<DT><B>__mp_info</B><DD>
Obtains information about a specific memory allocation by placing statistics
about <I>ptr</I> in <I>info</I>.  If <I>ptr</I> does not belong to a previously
allocated memory allocation or free memory block then <I>0</I> will be returned,
otherwise <I>1</I> will be returned and <I>info</I> will contain the following
information (note that a free memory block will only contain the <I>block</I> and
<I>size</I> fields and can be identified by not having the <I>allocated</I> flag
set):
<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>block</B></TD><TD>Pointer to first byte of alloc.<BR></TD></TR>
<TR VALIGN=top><TD><B>size</B></TD><TD>Size of alloc in bytes.<BR></TD></TR>
<TR VALIGN=top><TD><B>type</B></TD><TD>Type of function which allocated memory.<BR></TD></TR>
<TR VALIGN=top><TD><B>alloc</B></TD><TD>Allocation index.<BR></TD></TR>
<TR VALIGN=top><TD><B>realloc</B></TD><TD>Number of times reallocated.<BR></TD></TR>
<TR VALIGN=top><TD><B>thread</B></TD><TD>Thread identifier.<BR></TD></TR>
<TR VALIGN=top><TD><B>event</B></TD><TD>Event of last modification.<BR></TD></TR>
<TR VALIGN=top><TD><B>func</B></TD><TD>Function in which alloc took place.<BR></TD></TR>
<TR VALIGN=top><TD><B>file</B></TD><TD>File in which alloc took place.<BR></TD></TR>
<TR VALIGN=top><TD><B>line</B></TD><TD>Line number at which alloc took place.<BR></TD></TR>
<TR VALIGN=top><TD><B>stack</B></TD><TD>Pointer to function call stack.<BR></TD></TR>
<TR VALIGN=top><TD><B>typestr</B></TD><TD>Type stored in allocation.<BR></TD></TR>
<TR VALIGN=top><TD><B>typesize</B></TD><TD>Size of type stored in allocation.<BR></TD></TR>
<TR VALIGN=top><TD><B>userdata</B></TD><TD>User data associated with allocation.<BR></TD></TR>
<TR VALIGN=top><TD><B>allocated</B></TD><TD>Indicates if alloc was allocated.<BR></TD></TR>
<TR VALIGN=top><TD><B>freed</B></TD><TD>Indicates if alloc has been freed.<BR></TD></TR>
<TR VALIGN=top><TD><B>marked</B></TD><TD>Indicates if alloc has been marked.<BR></TD></TR>
<TR VALIGN=top><TD><B>profiled</B></TD><TD>Indicates if alloc has been profiled.<BR></TD></TR>
<TR VALIGN=top><TD><B>traced</B></TD><TD>Indicates if alloc has been traced.<BR></TD></TR>
<TR VALIGN=top><TD><B>internal</B></TD><TD>Indicates if alloc is internal.<BR></TD></TR>
</TABLE>

<DT><B>__mp_syminfo</B><DD>
Obtains symbolic information about a specific code address by placing statistics
about <I>ptr</I> in <I>info</I>.  If <I>ptr</I> does not belong to a function
symbol 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>name</B></TD><TD>Name of symbol.<BR></TD></TR>
<TR VALIGN=top><TD><B>object</B></TD><TD>File containing symbol.<BR></TD></TR>
<TR VALIGN=top><TD><B>addr</B></TD><TD>Start address of symbol.<BR></TD></TR>
<TR VALIGN=top><TD><B>size</B></TD><TD>Size of symbol.<BR></TD></TR>
<TR VALIGN=top><TD><B>file</B></TD><TD>Filename corresponding to address.<BR></TD></TR>
<TR VALIGN=top><TD><B>line</B></TD><TD>Line number corresponding to address.<BR></TD></TR>
</TABLE>

<DT><B>__mp_symbol</B><DD>
Obtains the name of a function symbol containing the code address specified in
<I>ptr</I>.  If <I>ptr</I> does not belong to a function symbol then <B>NULL</B>
will be returned.
<DT><B>__mp_printinfo</B><DD>
Displays information about a specific memory allocation containing <I>ptr</I> to
the standard error file stream.  If <I>ptr</I> does not belong to a previously
allocated memory allocation or free memory block then <I>0</I> will be returned,
otherwise <I>1</I> will be returned.  This function is intended to be called from
within a debugger.
<DT><B>__mp_snapshot</B><DD>
Returns the current event number, effectively taking a snapshot of the heap.
This number can then be used in later calls to <B>__mp_iterate</B>.
<DT><B>__mp_iterate</B><DD>
Iterates over all of the current allocated and freed memory allocations,
calling <I>func</I> with the start address of every memory allocation that has
been modified since event number <I>event</I>.  If <I>func</I> is <B>NULL</B> then
<B>__mp_printinfo</B> will be used as the callback function.  If <B>event</B> is
<I>0</I> then <I>func</I> will be called with the start address of every memory
allocation.  If <I>func</I> returns a negative number then the iteration process
will be stopped immediately.  If <I>func</I> returns a positive number above zero
then <B>__mp_iterate</B> will return the number of times <I>func</I> returned a
non-zero number after the iteration process has stopped.  The <I>data</I>
argument is passed directly to <I>func</I> as its second argument and is not
read by the mpatrol library.
<DT><B>__mp_iterateall</B><DD>
Iterates over all of the current allocated and freed memory allocations and any
free memory blocks, calling <I>func</I> with the start address of every memory
allocation or free block.  If <I>func</I> is <B>NULL</B> then <B>__mp_printinfo</B>
will be used as the callback function.  If <I>func</I> returns a negative number
then the iteration process will be stopped immediately.  If <I>func</I> returns a
positive number above zero then <B>__mp_iterate</B> will return the number of
times <I>func</I> returned a non-zero number after the iteration process has
stopped.  The <I>data</I> argument is passed directly to <I>func</I> as its second
argument and is not read by the mpatrol library.  Note that unlike
<B>__mp_iterate</B>, this function will also include internal memory allocations
made by the mpatrol library and is intended for walking the entire heap.
<DT><B>__mp_addallocentry</B><DD>
Adds an entry representing an allocation of size <I>size</I> to the leak table.
The allocation will be associated with a source filename of <I>file</I> and a
line number of <I>line</I> if the former is non-<B>NULL</B> and the latter is
non-zero.  If <I>file</I> is non-<B>NULL</B> and <I>line</I> is <I>0</I> then
<I>file</I> represents the name of the function that made the allocation.  If
<I>file</I> is <B>NULL</B> and <I>line</I> is non-zero then <I>line</I> represents
the code address at which the allocation was made.  If <I>file</I> is <B>NULL</B>
and <I>line</I> is <I>0</I> then the location of the allocation is unknown.
Returns <I>1</I> on success and <I>0</I> if there was no more memory available to
add another entry to the leak table.
<DT><B>__mp_addfreeentry</B><DD>
Adds an entry representing a deallocation of size <I>size</I> to the leak table.
The deallocation will be associated with a source filename of <I>file</I> and a
line number of <I>line</I> if the former is non-<B>NULL</B> and the latter is
non-zero.  If <I>file</I> is non-<B>NULL</B> and <I>line</I> is <I>0</I> then
<I>file</I> represents the name of the function that made the deallocation.  If
<I>file</I> is <B>NULL</B> and <I>line</I> is non-zero then <I>line</I> represents
the code address at which the deallocation was made.  If <I>file</I> is
<B>NULL</B> and <I>line</I> is <I>0</I> then the location of the deallocation is
unknown.  Returns <I>1</I> on success and <I>0</I> if there was no existing
allocation from the same location in the leak table.
<DT><B>__mp_clearleaktable</B><DD>
Deletes all of the existing entries in the leak table, making it empty.  This
will also affect the behaviour of the <B>LEAKTABLE</B> 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.
<DT><B>__mp_startleaktable</B><DD>
Starts the automatic logging of all memory allocations, reallocations and
deallocations to the leak table.  Returns <I>1</I> if such logging was already
being performed and <I>0</I> otherwise.
<DT><B>__mp_stopleaktable</B><DD>
Stops the automatic logging of all memory allocations, reallocations and
deallocations to the leak table.  Returns <I>1</I> if such logging was already