mptrace.1

debug source code under unix platform.

MPTRACE(1)               mpatrol library               MPTRACE(1)


NNAAMMEE
       mptrace  -  displays  tracing  information produced by the
       mpatrol library

SSYYNNOOPPSSIISS
       mmppttrraaccee [_o_p_t_i_o_n_s] [_f_i_l_e]

DDEESSCCRRIIPPTTIIOONN
       The mmppttrraaccee 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 mem-
       ory 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  cal-
       culated.

       When  the  TTRRAACCEE  option is used with the mpatrol library,
       statistics for all dynamic memory  allocations,  realloca-
       tions  and  deallocations  are written to a tracing output
       file.  The name of this  file  can  be  changed  with  the
       TTRRAACCEEFFIILLEE 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 con-
       tain a broader view of allocation behaviour throughout the
       entire program.

       The  _f_i_l_e  argument must be a valid mpatrol tracing output
       filename but if _f_i_l_e is omitted then mmppttrraaccee will use _m_p_a_-
       _t_r_o_l_._t_r_a_c_e  as the name of the tracing output file to use.
       If _f_i_l_e 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 alloca-
       tion simulation program can be written with the ----ssiimm--ffiillee
       option.  This program will have the identical memory allo-
       cation behaviour to the program which produced the  origi-
       nal  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 mmppttrraaccee command  by  using  the
       ----hhaattff--ffiillee  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 allo-
       cation tracing, and is being developed  by  Benjamin  Zorn
       and  Richard  Jones.   There  is a HATF DTD located in the
       _e_x_t_r_a directory in the mpatrol distribution.

       The mmppttrraaccee command will normally be built with  GUI  sup-
       port  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 mmppttrraaccee is run with the
       ----gguuii 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 dimen-
       sions 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
       ----bbaassee  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 ----ssppaaccee option.  A small delay can also
       be  added  after  drawing  each  memory  allocation  event
       through the use of the ----ddeellaayy option.

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

       The  idea  for  graphically displaying a memory map of the
       heap comes from the xxmmeemm 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 mmppttrraaccee  command  is  hopefully  more
       stable and contains a lot more functionality.

OOPPTTIIOONNSS
       ----gguuii [--ww]
              Displays the GUI (if supported).

       ----hhaattff--ffiillee _f_i_l_e [--HH]
              Specifies  that the trace should also be written to
              a file in Heap Allocation Trace Format (HATF).

       ----hheellpp [--hh]
              Displays a quick-reference option summary.

       ----ssiimm--ffiillee _f_i_l_e [--SS]
              Specifies that  a  trace-driven  memory  allocation
              simulation  program  written in C should be written
              to a file.

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

       ----vveerrbboossee [--vv]
              Specifies  that  the  tracing  table should be dis-
              played.

       ----vveerrssiioonn [--VV]
              Displays the version number of the mmppttrraaccee command.

GGUUII OOPPTTIIOONNSS
       ----aalllloocc _c_o_l_o_u_r
              Specifies  the  colour  to use for displaying allo-
              cated memory.  The default colour is _b_l_a_c_k.

       ----bbaassee _a_d_d_r_e_s_s
              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.

       ----ddeellaayy _l_e_n_g_t_h
              Specifies that a small delay of  a  certain  length
              should  be  added after drawing each memory alloca-
              tion 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.

       ----ffrreeee _c_o_l_o_u_r
              Specifies  the  colour  to  use for displaying free
              memory.  The default colour is _w_h_i_t_e.

       ----hheeiigghhtt _s_i_z_e
              Specifies the height (in  pixels)  of  the  drawing
              area.  The default height is _5_1_2.

       ----iinntteerrnnaall _c_o_l_o_u_r
              Specifies the colour to use for displaying internal
              heap memory.  The default colour is _r_e_d.

       ----ssppaaccee _s_i_z_e
              Specifies the size (in megabytes)  of  the  visible
              address  space  displayed  in  the memory map.  The
              default size is _4.

       ----uunnaalllloocc _c_o_l_o_u_r
              Specifies the colour to use for displaying  unallo-
              cated heap memory.  The default colour is _b_l_u_e.

       ----vviieeww--hheeiigghhtt _s_i_z_e
              Specifies  the  height  (in  pixels) of the window.
              The default height is _2_5_6.

       ----vviieeww--wwiiddtthh _s_i_z_e
              Specifies the width (in pixels) of the window.  The
              default width is _2_5_6.

       ----wwiiddtthh _s_i_z_e
              Specifies  the  width  (in  pixels)  of the drawing
              area.  The default width is _5_1_2.

SSEEEE AALLSSOO
       mmppaattrrooll(1), mmpprrooff(1), mmlleeaakk(1), mmppssyymm(1), mmppeeddiitt(1),  hheexx--
       wwoorrddss(1), XX(1), lliibbmmppaattrrooll(3), lliibbmmppaalllloocc(3).

       The mpatrol manual and reference card.

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

AAUUTTHHOORR
       Graeme S. Roy <[e-mail]>

CCOOPPYYRRIIGGHHTT
       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 Gen-
       eral 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.



Release 1.4               8 January 2002                        1