home | help 
MPTRACE(1)			 mpatrol library		      MPTRACE(1)

NAME
     mptrace - displays tracing information produced by the mpatrol library

SYNOPSIS
     mptrace [options] [file]

DESCRIPTION
     The  mptrace  command is a tool designed to read a tracing output file pro-
     duced by the mpatrol library and display the tracing information  that  was
     obtained.	The tracing information is a concise encoded trace of all of the
     memory  allocation  events  that occurred during a program's execution, and
     can be decoded into tabular or graphical form, along with any relevant sta-
     tistics that can be calculated.

     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 inten-
     tion  of  tracing is to gather concise details about each memory allocation
     event rather than complete information about some	or  all  memory  alloca-
     tions.   As a result, the mpatrol log files and profiling output files con-
     tain 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 pro-
     gram 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 de-
     termine which malloc library is most suitable to use for a specific  appli-
     cation.

     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 plat-
     forms 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 draw-
     ing 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 op-
     tion 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  ap-
     plication 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 documenta-
     tion 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 func-
     tionality.

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  ta-
	    ble, 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 trac-
	    ing output file.

     --delay length
	    Specifies that a small delay of a certain length should be added af-
	    ter drawing each memory allocation event.  The delay does not corre-
	    spond 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 dis-
	    played 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
     mpatrol(1),  mprof(1),  mleak(1),	mpsym(1),  mpedit(1), hexwords(1), X(1),
     libmpatrol(3), libmpalloc(3).

     The mpatrol manual and reference card.

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

AUTHOR
     Graeme S. Roy <graeme.roy@analog.com>

COPYRIGHT
     Copyright (C) 1997-2002 Graeme S. Roy <graeme.roy@analog.com>

     This library is free software; you can redistribute it and/or modify it un-
     der 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  op-
     tion) 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 FIT-
     NESS 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.

Release 1.4			 8 January 2002 		      MPTRACE(1)
home | help