libmpatrol.3

debug source code under unix platform.

following information:

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

\fBacount\fP	Total number of allocated blocks.
\fBatotal\fP	Total size of allocated blocks.
\fBfcount\fP	Total number of free blocks.
\fBftotal\fP	Total size of free blocks.
\fBgcount\fP	Total number of freed blocks.
\fBgtotal\fP	Total size of freed blocks.
\fBicount\fP	Total number of internal blocks.
\fBitotal\fP	Total size of internal blocks.
\fBmcount\fP	Total number of marked blocks.
\fBmtotal\fP	Total size of marked blocks.
.TE
.TP
\fB__mp_check\fP
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 \fBalloca\fP family of functions
are out of scope then this function will also cause them to be freed.
.TP
\fB__mp_prologue\fP
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):

.TS
c c c l.
\fBArgument 1\fP	\fBArgument 2\fP	\fBArgument 3\fP	\fBCalled by\fP

\fI-1\fP	\fIsize\fP	\fIalign\fP	\fBmalloc\fP, etc.
\fIptr\fP	\fIsize\fP	\fIalign\fP	\fBrealloc\fP, etc.
\fIptr\fP	\fI-1\fP	\fI0\fP	\fBfree\fP, etc.
\fIptr\fP	\fI-2\fP	\fI1\fP	\fBstrdup\fP, etc.
.TE
.TP
\fB__mp_epilogue\fP
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):

.TS
c l.
\fBArgument\fP	\fBCalled by\fP

\fIptr\fP	\fBmalloc\fP, \fBrealloc\fP, \fBstrdup\fP, etc.
\fI-1\fP	\fBfree\fP, etc.
.TE
.TP
\fB__mp_nomemory\fP
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 \fBNULL\fP.  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 \fBset_new_handler\fP and
will replace the handler installed by that function.
.TP
\fB__mp_printf\fP
Writes format string \fIfmt\fP with variable arguments to the log file, with
each line prefixed by \fI>\fP.  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.
.TP
\fB__mp_vprintf\fP
Writes format string \fIfmt\fP with variable argument list \fIargs\fP to the log
file, with each line prefixed by \fI>\fP.  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.
.TP
\fB__mp_locprintf\fP
Writes format string \fIfmt\fP with variable arguments to the log file, with
each line prefixed by \fI>\fP.  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.
.TP
\fB__mp_vlocprintf\fP
Writes format string \fIfmt\fP with variable argument list \fIargs\fP to the log
file, with each line prefixed by \fI>\fP.  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.
.TP
\fB__mp_logmemory\fP
Displays the contents of a block of memory beginning at \fIptr\fP, dumping
\fIsize\fP consecutive bytes to the log file in hexadecimal format.
.TP
\fB__mp_logstack\fP
Displays the current call stack, skipping \fIframes\fP stack frames from the
current stack frame before writing the symbolic stack trace to the log file.
Returns \fI1\fP if successful, or \fI0\fP if the call stack could not be
determined or if \fIframes\fP was too large for the current call stack.
.TP
\fB__mp_logaddr\fP
Displays information about a specific memory allocation containing \fIptr\fP to
the log file.  If \fIptr\fP does not belong to a previously allocated memory
allocation then \fI0\fP will be returned, otherwise \fI1\fP will be returned.
.TP
\fB__mp_edit\fP
Invokes a text editor to edit \fIfile\fP at line number \fIline\fP via the
\fBmpedit\fP command.  Returns \fI1\fP if the text editor was successfully
invoked, \fI-1\fP if there was an error, or \fI0\fP if there is no support for
this feature.  This function will only work on a system where the \fBEDIT\fP
option works.
.TP
\fB__mp_list\fP
Displays a context listing of \fIfile\fP at line number \fIline\fP via the
\fBmpedit\fP command.  Returns \fI1\fP if the listing was successfully
performed, \fI-1\fP if there was an error, or \fI0\fP if there is no support for
this feature.  This function will only work on a system where the \fBLIST\fP
option works.
.TP
\fB__mp_view\fP
Either invokes a text editor to edit \fIfile\fP at line number \fIline\fP or
displays a context listing of \fIfile\fP at line number \fIline\fP depending
on the setting of the \fBEDIT\fP and \fBLIST\fP options.  This is done via the
\fBmpedit\fP command and will have no effect if the \fBEDIT\fP and \fBLIST\fP
options are not set or if these options are not supported on the system.
Returns \fI1\fP if the edit or listing was successfully performed, \fI-1\fP if
there was an error, or \fI0\fP if neither of the options were set or if there is
no support for this feature.
.TP
\fB__mp_readcontents\fP
Reads the contents of a memory allocation contents file into the memory
allocation containing \fIptr\fP.  The name of the file is composed of the
\fIfile\fP string followed by the allocation index of the memory allocation
separated by a dot.  If \fIfile\fP is \fBNULL\fP then it is assumed to be
\fI.mpatrol\fP.  Returns \fI1\fP if the contents were read successfully and
\fI0\fP otherwise.
.TP
\fB__mp_writecontents\fP
Writes the contents of the memory allocation containing \fIptr\fP to an
allocation contents file.  The name of the file is composed of the \fIfile\fP
string followed by the allocation index of the memory allocation separated by
a dot.  If \fIfile\fP is \fBNULL\fP then it is assumed to be \fI.mpatrol\fP.
Returns \fI1\fP if the contents were written successfully and \fI0\fP otherwise.
.TP
\fB__mp_cmpcontents\fP
Compares the contents of the memory allocation containing \fIptr\fP with the
contents of a previously written allocation contents file.  The name of the file
is composed of the \fIfile\fP string followed by the allocation index of the
memory allocation separated by a dot.  If \fIfile\fP is \fBNULL\fP then it is
assumed to be \fI.mpatrol\fP.  Any differences are written to the mpatrol log
file.  Returns the number of differences found, or \fI-1\fP if there was an
error.
.TP
\fB__mp_remcontents\fP
Removes the memory allocation contents file that corresponds to the memory
allocation containing \fIptr\fP.  The name of the file is composed of the
\fIfile\fP string followed by the allocation index of the memory allocation
separated by a dot.  If \fIfile\fP is \fBNULL\fP then it is assumed to be
\fI.mpatrol\fP.  Returns \fI1\fP if the file was removed successfully and
\fI0\fP otherwise.
.PP
The following global variable is available for additional control in the mpatrol
library.  To use it you should include the \fImpatrol.h\fP header file:
.TP
\fB__mp_errno\fP
Contains the most recent error code encountered by the mpatrol library.  Its
value can be reset to \fIMP_ET_NONE\fP before calling an mpatrol library
function, and then examined afterwards, either by comparison with the known
error codes in the \fI__mp_errortype\fP enumeration, or with
\fB__mp_strerror\fP.
.SH LINKING
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:

.TS
l l.
\fBLibrary\fP	\fBReason\fP

\fI\-lmpatrol\fP	To use this library.
\fI\-lmpatrolmt\fP	To use the thread-safe mpatrol library.
\fI\-lmpalloc\fP	To use the release library.
\fI\-lmptools\fP	To use the mpatrol tools library.
\fI\-lld\fP	If built with COFF or XCOFF support.
\fI\-lelf\fP	If built with ELF support.
\fI\-lbfd\fP & \fI\-liberty\fP	If built with BFD support.
\fI\-lcl\fP	If built on HP/UX.
\fI\-lexc\fP	If built on IRIX or Tru64.
\fI\-limagehlp\fP	If built on Windows.
\fI\-lpthreads\fP	If built on AIX with threads support.
\fI\-lthread\fP	If built on DG/UX with threads support.
\fI\-lpthread\fP	If built on UNIX with threads support.
.TE
.PP
On UNIX platforms, if there were no calls to memory allocation functions before
\fI\-lmpatrol\fP or \fI\-lmpatrolmt\fP appears on the link line then the mpatrol
library will not be linked in if it is an archive library.  However, this can be
overridden by placing \fI\-umalloc\fP just before that point.
.PP
You may also wish to set your core file size limit to be zero before running
any programs linked with the mpatrol library as the extra memory that the
library uses can make such files much larger than normal, and if you are
planning on using a symbolic debugger then you won't need the core files anyway.
.SH ENVIRONMENT
The library can read certain options at run-time from an environment variable
called \fBMPATROL_OPTIONS\fP.  This variable must contain one or more valid
option keywords from the list below and must be no longer than 1024 characters
in length.  If \fBMPATROL_OPTIONS\fP is unset or empty then the default settings
will be used.
.PP
The syntax for options specified within the \fBMPATROL_OPTIONS\fP environment
variable is \fBOPTION\fP or \fBOPTION\fP=\fIVALUE\fP, where \fBOPTION\fP is a
keyword from the list below and \fIVALUE\fP is the setting for that option.  If
\fIVALUE\fP is numeric then it may be specified using binary, octal, decimal or
hexadecimal notation, with binary notation beginning with either \fI0b\fP or
\fI0B\fP.  If \fIVALUE\fP is a character string containing spaces then it may be
quoted using double quotes.  No whitespace may appear between the \fI=\fP sign,
but whitespace must appear between different options.  Note that option keywords
can be given in lowercase as well as uppercase, or a mixture of both.
.TP
\fBALLOCBYTE\fP=\fIunsigned integer\fP
Specifies an 8-bit byte pattern with which to prefill newly-allocated memory.
This can be used to detect the use of memory which has not been initialised
after allocation.  Note that this setting will not affect memory allocated with
\fBcalloc\fP or \fBrecalloc\fP as these functions always prefill allocated
memory with an 8-bit byte pattern of zero.  Default value:
\fBALLOCBYTE\fP=\fI0xFF\fP.
.TP
\fBALLOCSTOP\fP=\fIunsigned integer\fP
Specifies an allocation index at which to stop the program when it is being
allocated.  When the number of memory allocations reaches this number the
program will be halted, and its state may be examined at that point by using
a suitable debugger.  Note that this setting will be ignored if its value is
zero.  Default value: \fBALLOCSTOP\fP=\fI0\fP.
.TP
\