refcard.tex

debug source code under unix platform.

% mpatrol
% A library for controlling and tracing dynamic memory allocations.
% Copyright (C) 1997-2002 Graeme S. Roy <[e-mail]>
%
% This library is free software; you can redistribute it and/or
% modify it under the terms of the GNU Library General Public
% License as published by the Free Software Foundation; either
% version 2 of the License, or (at your option) any later version.
%
% This library is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
% Library General Public License for more details.
%
% You should have received a copy of the GNU Library General Public
% License along with this library; if not, write to the Free
% Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
% MA 02111-1307, USA.

% LaTeX reference card for mpatrol

% $Id: refcard.tex,v 1.33 2002/01/08 20:45:08 graeme Exp $

\documentclass[a4paper,landscape,final]{article}

\usepackage{multicol}

% Adapt the page dimensions to the paper size.

\setlength{\textwidth}{\paperwidth}
\addtolength{\textwidth}{-1in}
\setlength{\textheight}{\paperheight}
\addtolength{\textheight}{-1in}
\setlength{\headheight}{0in}
\setlength{\headsep}{0in}
\setlength{\footskip}{0in}
\setlength{\parindent}{0in}
\setlength{\columnsep}{.5in}
\setlength{\oddsidemargin}{-.5in}
\setlength{\evensidemargin}{-.5in}
\setlength{\topmargin}{-.5in}

% Define new commands for formatting the headings and options.

\newcommand{\heading}[1]{\textbf{\normalsize #1}}
\newcommand{\command}[1]{\textbf{#1}}
\newcommand{\function}[1]{\texttt{#1()}}
\newcommand{\variable}[1]{\texttt{#1}}
\newcommand{\error}[1]{\texttt{#1}}
\newcommand{\flag}[1]{\textbf{---#1}}
\newcommand{\flagpar}[2]{\flag{#1} \texttt{<}\textit{#2}\texttt{>}}
\newcommand{\option}[1]{\texttt{#1}}
\newcommand{\optionarg}[2]{\option{#1}\texttt{=<#2>}}
\newcommand{\optionpar}[2]{\option{#1}\texttt{=<}\textit{#2}\texttt{>}}

\begin{document}

\pagestyle{empty}

\footnotesize

\begin{multicols}{3}{\textbf{\Large mpatrol reference card}}

\vskip 12pt

The mpatrol library can read certain options at run-time from an environment
variable called \texttt{MPATROL\_OPTIONS}.  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 \texttt{MPATROL\_OPTIONS} is unset or empty then the
default settings will be used.

The \texttt{LOGDIR}, \texttt{PROFDIR} and \texttt{TRACEDIR} environment
variables are also read in order to determine where the log file, profiling
output file and tracing output file should go.  Note that if they are set then
the default filenames for the log file, profiling output file and tracing output
file will also be changed.

\vskip 12pt
\heading{Library behaviour}
\vskip 6pt

\begin{description}
\item[\option{HELP}]
Displays a quick-reference option summary.
\item[\optionpar{PROGFILE}{string}]
Specifies an alternative filename with which to locate the executable file
containing the program's symbols.
\item[\optionpar{CHECK}{unsigned range}]
Specifies a range of allocation indices at which to check the integrity of free
memory and overflow buffers.
\item[\option{EDIT}]
Specifies that a text editor should be invoked to edit any relevant source files
that are associated with any warnings or errors when they occur.
\item[\option{LIST}]
Specifies that a context listing should be shown for any relevant source files
that are associated with any warnings or errors when they occur.
\item[\optionpar{DEFALIGN}{unsigned integer}]
Specifies the default alignment for general-purpose memory allocations, which
must be a power of two.
\item[\option{NOPROTECT}]
Specifies that the mpatrol library's internal data structures should not be made
read-only after every memory allocation, reallocation or deallocation.
\item[\option{SAFESIGNALS}]
Instructs the library to save and replace certain signal handlers during the
execution of library code and to restore them afterwards.
\item[\option{CHECKFORK}]
Checks at every call to see if the process has been forked in case new log,
profiling and tracing output files need to be started.
\item[\option{USEMMAP}]
Specifies that the library should use \function{mmap} instead of \function{sbrk}
to allocate user memory on UNIX platforms.
\end{description}

\vskip 12pt
\heading{Logging and tracing}
\vskip 6pt

\begin{description}
\item[\optionpar{LOGFILE}{string}]
Specifies an alternative file in which to place all diagnostics from the mpatrol
library.
\item[\option{LOGALLOCS}]
Specifies that all memory allocations are to be logged and sent to the log file.
\item[\option{LOGREALLOCS}]
Specifies that all memory reallocations are to be logged and sent to the log
file.
\item[\option{LOGFREES}]
Specifies that all memory deallocations are to be logged and sent to the log
file.
\item[\option{LOGMEMORY}]
Specifies that all memory operations are to be logged and sent to the log file.
\item[\option{LOGALL}]
Equivalent to the \option{LOGALLOCS}, \option{LOGREALLOCS}, \option{LOGFREES}
and \option{LOGMEMORY} options specified together.
\item[\option{TRACE}]
Specifies that all memory allocations are to be traced and sent to the tracing
output file.
\item[\optionpar{TRACEFILE}{string}]
Specifies an alternative file in which to place all memory allocation tracing
information from the mpatrol library.
\item[\option{LEAKTABLE}]
Specifies that the leak table should be automatically used and a leak table
summary should be displayed at the end of program execution.
\item[\option{SHOWFREE}]
Specifies that a summary of all of the free memory blocks should be displayed at
the end of program execution.
\item[\option{SHOWFREED}]
Specifies that a summary of all of the freed memory allocations should be
displayed at the end of program execution.
\item[\option{SHOWUNFREED}]
Specifies that a summary of all of the unfreed memory allocations should be
displayed at the end of program execution.
\item[\option{SHOWMAP}]
Specifies that a memory map of the entire heap should be displayed at the end of
program execution.
\item[\option{SHOWSYMBOLS}]
Specifies that a summary of all of the function symbols read from the program's
executable file should be displayed at the end of program execution.
\item[\option{SHOWALL}]
Equivalent to the \option{SHOWFREE}, \option{SHOWFREED}, \option{SHOWUNFREED},
\option{SHOWMAP} and \option{SHOWSYMBOLS} options specified together.
\item[\option{USEDEBUG}]
Specifies that any debugging information in the executable file should be used
to obtain additional source-level information.
\end{description}

\vskip 12pt
\heading{General errors}
\vskip 6pt

\begin{description}
\item[\option{CHECKALLOCS}]
Checks that no attempt is made to allocate a block of memory of size zero.
\item[\option{CHECKREALLOCS}]
Checks that no attempt is made to reallocate a \texttt{NULL} pointer or resize
an existing block of memory to size zero.
\item[\option{CHECKFREES}]
Checks that no attempt is made to deallocate a \texttt{NULL} pointer.
\item[\option{CHECKMEMORY}]
Checks that no attempt is made to perform a zero-length memory operation on a
\texttt{NULL} pointer.
\item[\option{CHECKALL}]
Equivalent to the \option{CHECKALLOCS}, \option{CHECKREALLOCS},
\option{CHECKFREES} and \option{CHECKMEMORY} options specified together.
\item[\optionpar{ALLOCBYTE}{unsigned integer}]
Specifies an 8-bit byte pattern with which to prefill newly-allocated memory.
\item[\optionpar{FREEBYTE}{unsigned integer}]
Specifies an 8-bit byte pattern with which to prefill newly-freed memory.
\item[\optionpar{NOFREE}{unsigned integer}]
Specifies that a number of recently-freed memory allocations should be prevented
from being returned to the free memory pool.
\item[\option{PRESERVE}]
Specifies that any reallocated or freed memory allocations should preserve their
original contents.
\end{description}

\vskip 12pt
\heading{Overwrites and underwrites}
\vskip 6pt

\begin{description}
\item[\optionpar{OFLOWSIZE}{unsigned integer}]
Specifies the size in bytes to use for all overflow buffers, which must be a
power of two.
\item[\optionpar{OFLOWBYTE}{unsigned integer}]
Specifies an 8-bit byte pattern with which to fill the overflow buffers of all
memory allocations.
\item[\option{OFLOWWATCH}]
Specifies that watch point areas should be used for overflow buffers rather than
filling with the overflow byte.
\item[\optionarg{PAGEALLOC}{LOWER|UPPER}]
Specifies that each individual memory allocation should occupy at least one page
of virtual memory and should be placed at the lowest or highest point within
these pages.
\item[\option{ALLOWOFLOW}]
Specifies that a warning rather than an error should be produced if any memory
operation function overflows the boundaries of a memory allocation, and that
the operation should still be performed.
\end{description}

\vskip 12pt
\heading{Using with a debugger}
\vskip 6pt

\begin{description}
\item[\optionpar{ALLOCSTOP}{unsigned integer}]
Specifies an allocation index at which to stop the program when it is being
allocated.
\item[\optionpar{REALLOCSTOP}{unsigned integer}]
Specifies an allocation index at which to stop the program when a memory
allocation is being reallocated.
\item[\optionpar{FREESTOP}{unsigned integer}]
Specifies an allocation index at which to stop the program when it is being
freed.
\end{description}

\vskip 12pt
\heading{Testing}
\vskip 6pt

\begin{description}
\item[\optionpar{LIMIT}{unsigned integer}]
Specifies the limit in bytes at which all memory allocations should fail if the
total allocated memory should increase beyond this.
\item[\optionpar{FAILFREQ}{unsigned integer}]
Specifies the frequency at which all memory allocations will randomly fail.
\item[\optionpar{FAILSEED}{unsigned integer}]
Specifies the random number seed which will be used when determining which
memory allocations will randomly fail.
\item[\optionpar{UNFREEDABORT}{unsigned integer}]
Specifies the minimum number of unfreed allocations at which to abort the
program just before program termination.
\end{description}

\vskip 12pt
\heading{Profiling}
\vskip 6pt

\begin{description}
\item[\option{PROF}]
Specifies that all memory allocations are to be profiled and sent to the
profiling output file.
\item[\optionpar{PROFFILE}{string}]
Specifies an alternative file in which to place all memory allocation profiling
information from the mpatrol library.
\item[\optionpar{AUTOSAVE}{unsigned integer}]
Specifies the frequency at which to periodically write the profiling data to the
profiling output file.
\item[\optionpar{SMALLBOUND}{unsigned integer}]
Specifies the limit in bytes up to which memory allocations should be classified
as small allocations for profiling purposes.
\item[\optionpar{MEDIUMBOUND}{unsigned integer}]
Specifies the limit in bytes up to which memory allocations should be classified
as medium allocations for profiling purposes.
\item[\optionpar{LARGEBOUND}{unsigned integer}]
Specifies the limit in bytes up to which memory allocations should be classified
as large allocations for profiling purposes.
\end{description}

\vskip 12pt

All of the function definitions in \texttt{mpatrol.h} can be disabled by
defining the \texttt{NDEBUG} preprocessor macro, which is the same macro used
to control the behaviour of the \function{assert} function.  If \texttt{NDEBUG}
is defined then no macro redefinition of functions will take place and all
special mpatrol library functions will evaluate to empty statements.  The
\texttt{mpalloc.h} header file will also be included in this case.  It is
intended that the \texttt{NDEBUG} preprocessor macro be defined in release
builds.

The \function{MP\_MALLOC} family of functions that are defined in
\texttt{mpalloc.h} are also defined in \texttt{mpatrol.h} when \texttt{NDEBUG}
is not defined.  The mpatrol versions of these functions contain more debugging
information than the mpalloc versions do, but they do not call the allocation
failure handler when no more memory is available (they cause the \error{OUTMEM}
error message to be given instead).

There may be problems during preprocessing when the preprocessor macros defining
the replacement C$++$ operators in \texttt{mpatrol.h} are used.  If this is the
case then either the \texttt{MP\_NOCPLUSPLUS} preprocessor macro can be defined
to disable all C$++$ support, or the \texttt{MP\_NONEWDELETE} preprocessor macro
can be defined to prevent the debugging versions of \texttt{operator new} and
\texttt{operator delete} from being used by default.  The preprocessor macros
\texttt{MP\_NEW}, \texttt{MP\_NEW\_NOTHROW} and \texttt{MP\_DELETE} will then