Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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
       produced	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 statistics 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
       intention of tracing is to gather concise details about each memory al-
       location	 event rather than complete information	about some or all mem-
       ory allocations.	 As a result, the mpatrol log files and	profiling out-
       put files contain more detailed information about individual memory al-
       locations, 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 stan-
       dard 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 mem-
       ory 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 li-
       brary), 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 mem-
       ory 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 ap-
       pear in the quick-reference option summary produced by the  --help  op-
       tion.   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  con-
       tains 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  pro-
	      gram 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 dis-
	      played 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 de-
	      fault colour is white.

       --height	size
	      Specifies	 the  height (in pixels) of the	drawing	area.  The de-
	      fault 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 mem-
	      ory.  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 de-
	      fault 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
       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 MER-
       CHANTABILITY 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 Li-
       cense along with	this library; if not, write to the Free	Software Foun-
       dation, Inc., 59	Temple Place, Suite 330, Boston, MA 02111-1307,	USA.

Release	1.4			8 January 2002			    MPTRACE(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | GUI OPTIONS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mptrace&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help