refcard.tex

debug source code under unix platform.

have to be used instead.

On systems that support it, global functions (with C linkage) in an executable
file or shared library whose names begin with \texttt{\_\_mp\_init\_} will be
noted when the mpatrol library first starts up and is reading the symbols.  Such
functions will then be called as soon as the mpatrol library is initialised,
which can be useful if the initialisation occurs before \function{main} is
called.  These functions must accept no arguments and must return no value.
Similar behaviour exists for global functions whose names begin with
\texttt{\_\_mp\_fini\_}, except that such functions will be executed when the
mpatrol library terminates.

\vskip 12pt
\heading{C dynamic memory allocation functions}
\vskip 6pt

\begin{description}
\item[\function{malloc}]
\hfill Allocates memory.
\item[\function{calloc}]
\hfill Allocates zero-filled memory.
\item[\function{memalign}]
\hfill Allocates memory with a specified alignment.
\item[\function{valloc}]
\hfill Allocates page-aligned memory.
\item[\function{pvalloc}]
\hfill Allocates a number of pages.
\item[\function{alloca}]
\hfill Allocates temporary memory.
\item[\function{strdup}]
\hfill Duplicates a string.
\item[\function{strndup}]
\hfill Duplicates a string with a maximum length.
\item[\function{strsave}]
\hfill Duplicates a string.
\item[\function{strnsave}]
\hfill Duplicates a string with a maximum length.
\item[\function{strdupa}]
\hfill Duplicates a string.
\item[\function{strndupa}]
\hfill Duplicates a string with a maximum length.
\item[\function{realloc}]
\hfill Resizes memory.
\item[\function{reallocf}]
\hfill Resizes memory and frees on failure.
\item[\function{recalloc}]
\hfill Resizes memory allocated by \function{calloc}.
\item[\function{expand}]
\hfill Resizes memory but does not relocate it.
\item[\function{free}]
\hfill Frees memory.
\item[\function{cfree}]
\hfill Frees memory allocated by \function{calloc}.
\item[\function{dealloca}]
\hfill Explicitly frees temporary memory.
\end{description}

\vskip 12pt
\heading{C dynamic memory extension functions}
\vskip 6pt

\begin{description}
\item[\function{xmalloc}]
\hfill Allocates memory without failure.
\item[\function{xcalloc}]
\hfill Allocates zero-filled memory without failure.
\item[\function{xstrdup}]
\hfill Duplicates a string without failure.
\item[\function{xrealloc}]
\hfill Resizes memory without failure.
\item[\function{xfree}]
\hfill Frees memory.
\end{description}

\vskip 12pt
\heading{C dynamic memory alternative functions}
\vskip 6pt

\begin{description}
\item[\function{MP\_MALLOC}]
\hfill Allocates memory without failure.
\item[\function{MP\_CALLOC}]
\hfill Allocates zero-filled memory without failure.
\item[\function{MP\_STRDUP}]
\hfill Duplicates a string without failure.
\item[\function{MP\_REALLOC}]
\hfill Resizes memory without failure.
\item[\function{MP\_FREE}]
\hfill Frees memory.
\item[\function{MP\_FAILURE}]
\hfill Sets the allocation failure handler.
\end{description}

\vskip 12pt
\heading{C$++$ dynamic memory allocation functions}
\vskip 6pt

\begin{description}
\item[\texttt{operator new}]
\hfill Allocates memory.
\item[\texttt{operator new[]}]
\hfill Allocates memory for an array.
\item[\texttt{operator delete}]
\hfill Frees memory.
\item[\texttt{operator delete[]}]
\hfill Frees memory allocated by \texttt{new[]}.
\item[\function{set\_new\_handler}]
\hfill Sets up an allocation failure handler.
\end{description}

\vskip 12pt
\heading{C memory operation functions}
\vskip 6pt

\begin{description}
\item[\function{memset}]
\hfill Fills memory with a specific byte.
\item[\function{bzero}]
\hfill Fills memory with the zero byte.
\item[\function{memccpy}]
\hfill Copies memory up to a specific byte.
\item[\function{memcpy}]
\hfill Copies non-overlapping memory.
\item[\function{memmove}]
\hfill Copies possibly-overlapping memory.
\item[\function{bcopy}]
\hfill Copies possibly-overlapping memory.
\item[\function{memcmp}]
\hfill Compares two blocks of memory.
\item[\function{bcmp}]
\hfill Compares two blocks of memory.
\item[\function{memchr}]
\hfill Searches memory for a specific byte.
\item[\function{memmem}]
\hfill Searches memory for specific bytes.
\end{description}

\vskip 12pt
\heading{mpatrol library functions}
\vskip 6pt

\begin{description}
\item[\function{\_\_mp\_atexit}]
\hfill Registers termination functions.
\item[\function{\_\_mp\_setoption}]
\hfill Sets an mpatrol library option.
\item[\function{\_\_mp\_getoption}]
\hfill Returns an mpatrol library option.
\item[\function{\_\_mp\_libversion}]
\hfill Returns the mpatrol library version.
\item[\function{\_\_mp\_strerror}]
\hfill Returns an error message string.
\item[\function{\_\_mp\_function}]
\hfill Returns an allocation type function name.
\item[\function{\_\_mp\_setuser}]
\hfill Sets the user data for an allocation.
\item[\function{\_\_mp\_setmark}]
\hfill Sets the marked flag for an allocation.
\item[\function{\_\_mp\_info}]
\hfill Returns information for an allocation.
\item[\function{\_\_mp\_syminfo}]
\hfill Returns symbol information for an address.
\item[\function{\_\_mp\_symbol}]
\hfill Returns symbol name for an address.
\item[\function{\_\_mp\_printinfo}]
\hfill Displays information for an allocation.
\item[\function{\_\_mp\_snapshot}]
\hfill Returns the current heap event number.
\item[\function{\_\_mp\_iterate}]
\hfill Iterates over allocations in the heap.
\item[\function{\_\_mp\_iterateall}]
\hfill Iterates over all allocations in the heap.
\item[\function{\_\_mp\_addallocentry}]
\hfill Adds an allocation to the leak table.
\item[\function{\_\_mp\_addfreeentry}]
\hfill Adds a deallocation to the leak table.
\item[\function{\_\_mp\_clearleaktable}]
\hfill Clears the leak table.
\item[\function{\_\_mp\_startleaktable}]
\hfill Starts automatic leak table entries.
\item[\function{\_\_mp\_stopleaktable}]
\hfill Stops automatic leak table entries.
\item[\function{\_\_mp\_leaktable}]
\hfill Displays the leak table.
\item[\function{\_\_mp\_memorymap}]
\hfill Displays a map of memory in the heap.
\item[\function{\_\_mp\_summary}]
\hfill Displays a summary of library statistics.
\item[\function{\_\_mp\_stats}]
\hfill Returns statistics about the heap.
\item[\function{\_\_mp\_check}]
\hfill Validates memory in the heap.
\item[\function{\_\_mp\_prologue}]
\hfill Sets up an allocation prologue handler.
\item[\function{\_\_mp\_epilogue}]
\hfill Sets up an allocation epilogue handler.
\item[\function{\_\_mp\_nomemory}]
\hfill Sets up an allocation failure handler.
\item[\function{\_\_mp\_printf}]
\hfill Writes user data to the log file.
\item[\function{\_\_mp\_vprintf}]
\hfill Writes user data to the log file.
\item[\function{\_\_mp\_locprintf}]
\hfill Logs user data and the location.
\item[\function{\_\_mp\_vlocprintf}]
\hfill Logs user data and the location.
\item[\function{\_\_mp\_logmemory}]
\hfill Displays a hex dump of memory.
\item[\function{\_\_mp\_logstack}]
\hfill Displays the current call stack.
\item[\function{\_\_mp\_logaddr}]
\hfill Displays information for an allocation.
\item[\function{\_\_mp\_edit}]
\hfill Invokes a text editor on a source file.
\item[\function{\_\_mp\_list}]
\hfill Lists a source file at a specific line.
\item[\function{\_\_mp\_view}]
\hfill Edits or lists a source file.
\item[\function{\_\_mp\_readcontents}]
\hfill Reads the contents of a memory allocation.
\item[\function{\_\_mp\_writecontents}]
\hfill Writes the contents of a memory allocation.
\item[\function{\_\_mp\_cmpcontents}]
\hfill Compares the contents of a memory allocation.
\item[\function{\_\_mp\_remcontents}]
\hfill Removes the contents of a memory allocation.
\end{description}

\vskip 12pt
\heading{mpatrol library variables}
\vskip 6pt

\begin{description}
\item[\variable{\_\_mp\_errno}]
\hfill Contains the most recent error code.
\end{description}

\vskip 12pt

The following table lists the warnings and errors that are likely to appear in
the mpatrol log file when problems with dynamic memory allocations and memory
operations occur.  Other types of warnings and errors may also appear in the log
file, but they are likely to be associated with parsing options and reading
symbols from executable files and so should be self-explanatory.

\vskip 12pt
\heading{Error abbreviation codes}
\vskip 6pt

\begin{description}
\item[\error{ALLOVF}]
\hfill Allocation has a corrupted overflow buffer.
\item[\error{ALLZER}]
\hfill Attempt to create an allocation of size 0.
\item[\error{BADALN}]
\hfill Alignment is not a power of two.
\item[\error{FRDCOR}]
\hfill Freed allocation has memory corruption.
\item[\error{FRDOPN}]
\hfill Attempt to perform operation on freed memory.
\item[\error{FRDOVF}]
\hfill Freed allocation has a corrupted overflow buffer.
\item[\error{FRECOR}]
\hfill Free memory corruption.
\item[\error{FREMRK}]
\hfill Attempt to free a marked memory allocation.
\item[\error{FRENUL}]
\hfill Attempt to free a \texttt{NULL} pointer.
\item[\error{FREOPN}]
\hfill Attempt to perform operation on free memory.
\item[\error{ILLMEM}]
\hfill Illegal memory access.
\item[\error{INCOMP}]
Attempt to resize or free memory allocated with an incompatible function.
\item[\error{MAXALN}]
\hfill Alignment is greater than the system page size.
\item[\error{MISMAT}]
Attempt to resize or free memory not pointing to the start of a memory
allocation.
\item[\error{NOTALL}]
\hfill Pointer has not been allocated.
\item[\error{NULOPN}]
\hfill Attempt to perform operation on a \texttt{NULL} pointer.
\item[\error{OUTMEM}]
\hfill Out of memory.
\item[\error{PRVFRD}]
Attempt to resize of free memory that has previously been freed.
\item[\error{RNGOVF}]
Attempt to perform a memory operation that overflows a memory allocation.
\item[\error{RNGOVL}]
Attempt to perform a non-overlapping memory operation that overlaps.
\item[\error{RSZNUL}]
\hfill Attempt to resize a \texttt{NULL} pointer.
\item[\error{RSZZER}]
\hfill Attempt to resize an allocation to size 0.
\item[\error{STROVF}]
Attempt to perform a string operation that overflows a memory allocation.
\item[\error{ZERALN}]
\hfill Alignment 0 is invalid.
\end{description}

\vskip 12pt

The commands that are distributed with the mpatrol library all parse their