NAME

SYNOPSIS

DESCRIPTION

When the TRACE option is used with the mpatrol library, statistics for all dynamic memory allocations, reallocations and deallocations are written to a tracing output file. The name of this file can be changed with the TRACEFILE option.

Only allocations, reallocations and deallocations are recorded. The intention of tracing is to gather concise details about each memory allocation event rather than complete information about some or all memory allocations. As a result, the mpatrol log files and profiling output files contain more detailed information about individual memory allocations, whereas the tracing output files contain a broader view of allocation behaviour throughout the entire program.

The file argument must be a valid mpatrol tracing output filename but if file is omitted then mptrace will use mpatrol.trace as the name of the tracing output file to use. If file is given as - then the standard input file stream will be used as the tracing output file.

A C source file containing a trace-driven memory allocation simulation program can be written with the --sim-file option. This program will have the identical memory allocation behaviour to the program which produced the original trace file. This option can be useful to use if you wish to determine which malloc library is most suitable to use for a specific application.

A trace file in Heap Allocation Trace Format (HATF) can also be written out by the mptrace command by using the --hatf-file option. It takes the name of the HATF trace file to be written as an argument and writes out the HATF version of the mpatrol tracing output file given as input when it is being processed. The HATF file format is an attempt to standardise trace file formats for memory allocation tracing, and is being developed by Benjamin Zorn and Richard Jones. There is a HATF DTD located in the extra directory in the mpatrol distribution.

The mptrace command will normally be built with GUI support on UNIX platforms that are running X Windows. This means that a graphical memory map display of the heap will be shown in a window every time mptrace is run with the --gui option. This display is updated every time a new event is read from the tracing output file and by default uses the colour red for internal heap memory (used by the mpatrol library), blue for unallocated heap memory, black for allocated memory and white for free memory. Options exist to change this colour scheme, as well as the dimensions of the drawing area and the window.

By default, it is assumed that the start address of the first event that appears in the tracing output file is the base address of the memory map displayed in the window. If the heap grows downwards then this assumption will be incorrect (since nothing will be displayed) and so the --base option must be used to specify a reasonable lower bound for the final memory map. In addition, the visible address space displayed in the memory map is fixed to a certain size (4 megabytes by default), but this can be changed with the --space option. A small delay can also be added after drawing each memory allocation event through the use of the --delay option.

Note that any options that are specific to the GUI version of mptrace are read by the X command line parser rather than directly by mptrace. As a result they are parsed according to X toolkit rules and do not appear in the quick-reference option summary produced by the --help option. The application class for setting mptrace X resources is called MPTrace.

The idea for graphically displaying a memory map of the heap comes from the xmem tool supplied with the University of Toronto Computer Systems Research Institute malloc library, written by Mark Moraes. However, the documentation for that tool remarks that it was written as a quick and dirty hack. The mptrace command is hopefully more stable and contains a lot more functionality.

OPTIONS

--gui [-w]

Displays the GUI (if supported).

--hatf-file file [-H]

Specifies that the trace should also be written to a file in Heap Allocation Trace Format (HATF).

--help [-h]

Displays a quick-reference option summary.

--sim-file file [-S]

Specifies that a trace-driven memory allocation simulation program written in C should be written to a file.

--source [-s]

Displays source-level information for each event in the tracing table, if available.

--verbose [-v]

Specifies that the tracing table should be displayed.

--version [-V]

Displays the version number of the mptrace command.

GUI OPTIONS

--alloc colour

Specifies the colour to use for displaying allocated memory. The default colour is black.

--base address

Specifies the base address of the visible address space displayed in the memory map. The default address is calculated at run-time from the start address of the first memory allocation event in the tracing output file.

--delay length

Specifies that a small delay of a certain length should be added after drawing each memory allocation event. The delay does not correspond to a specific unit of time, but experimentation with the length should yield satisfactory results. The default delay is 0.

--free colour

Specifies the colour to use for displaying free memory. The default colour is white.

--height size

Specifies the height (in pixels) of the drawing area. The default height is 512.

--internal colour

Specifies the colour to use for displaying internal heap memory. The default colour is red.

--space size

Specifies the size (in megabytes) of the visible address space displayed in the memory map. The default size is 4.

--unalloc colour

Specifies the colour to use for displaying unallocated heap memory. The default colour is blue.

--view-height size

Specifies the height (in pixels) of the window. The default height is 256.

--view-width size

Specifies the width (in pixels) of the window. The default width is 256.

--width size

Specifies the width (in pixels) of the drawing area. The default width is 512.

SEE ALSO

The mpatrol manual and reference card.

http://www.cbmamiga.demon.co.uk/mpatrol/

AUTHOR

COPYRIGHT

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.