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

NAME
     mpatrol - runs programs using the mpatrol library

SYNOPSIS
     mpatrol [options] <command> [arguments]

DESCRIPTION
     The  mpatrol  command  is	used to set various mpatrol library options when
     running command with its arguments.  In most cases, command must have  been
     linked  with  the	mpatrol  library, unless the --dynamic option is used in
     which case command need only have been dynamically linked.

     All mpatrol library diagnostics are sent to the file mpatrol.%n.log in  the
     current  directory by default (where %n is the current process id) but this
     can be changed using the --log-file option.  Similarly, the default profil-
     ing output filename is mpatrol.%n.out and the default tracing output  file-
     name is mpatrol.%n.trace.

OPTIONS
     All  of  the  following  options  (except	--dynamic,  --help,  --read-env,
     --show-env, --threads and --version) correspond to their listed mpatrol li-
     brary option.  See libmpatrol(3) for more details on these options.

     --alloc-byte <unsigned integer> [-a]
	    [ALLOCBYTE]  Specifies an 8-bit byte pattern with which  to  prefill
	    newly-allocated memory.

     --alloc-stop <unsigned integer> [-A]
	    [ALLOCSTOP]  Specifies an allocation index at which to stop the pro-
	    gram when it is being allocated.

     --allow-oflow [-M]
	    [ALLOWOFLOW]   Specifies  that a warning rather than an error should
	    be produced if any memory operation function  overflows  the  bound-
	    aries of a memory allocation, and that the operation should still be
	    performed.

     --auto-save <unsigned integer> [-s]
	    [AUTOSAVE]	 Specifies  the frequency at which to periodically write
	    the profiling data to the profiling output file.

     --check <unsigned range> [-c]
	    [CHECK]  Specifies a range of allocation indices at which  to  check
	    the integrity of free memory and overflow buffers.

     --check-all [-C]
	    [CHECKALL]	 Equivalent  to  the  --check-allocs,  --check-reallocs,
	    --check-frees and --check-memory options specified together.

     --check-allocs
	    [CHECKALLOCS]  Checks that no attempt is made to allocate a block of
	    memory of size zero.

     --check-fork
	    [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.

     --check-frees
	    [CHECKFREES]  Checks that no attempt is made to  deallocate  a  NULL
	    pointer.

     --check-memory
	    [CHECKMEMORY]   Checks  that  no  attempt is made to perform a zero-
	    length memory operation on a NULL pointer.

     --check-reallocs
	    [CHECKREALLOCS]  Checks that no attempt is made to reallocate a NULL
	    pointer or resize an existing block of memory to size zero.

     --def-align <unsigned integer> [-D]
	    [DEFALIGN]	Specifies the default alignment for general-purpose mem-
	    ory allocations, which must be a power of two.

     --dynamic [-d]
	    Specifies that programs which were not linked with the  mpatrol  li-
	    brary  should  also  be  traced,  but  only if they were dynamically
	    linked.  This option will only work if the system dynamic linker has
	    the ability to preload a set of user-specified shared libraries  via
	    a special environment variable.

     --edit [-e]
	    [EDIT]   Specifies	that a text editor should be invoked to edit any
	    relevant source files that are associated with any warnings  or  er-
	    rors when they occur.

     --fail-freq <unsigned integer> [-q]
	    [FAILFREQ]	 Specifies the frequency at which all memory allocations
	    will randomly fail.

     --fail-seed <unsigned integer> [-Q]
	    [FAILSEED]	Specifies the random number seed which will be used when
	    determining which memory allocations will randomly fail.

     --free-byte <unsigned integer> [-f]
	    [FREEBYTE]	Specifies an 8-bit byte pattern with  which  to  prefill
	    newly-freed memory.

     --free-stop <unsigned integer> [-F]
	    [FREESTOP]	 Specifies an allocation index at which to stop the pro-
	    gram when it is being freed.

     --help [-h]
	    Displays a quick-reference option summary.

     --large-bound <unsigned integer>
	    [LARGEBOUND]  Specifies the limit in bytes up to which memory  allo-
	    cations should be classified as large allocations for profiling pur-
	    poses.

     --leak-table
	    [LEAKTABLE]  Specifies  that  the leak table should be automatically
	    used and a leak table summary should be displayed at the end of pro-
	    gram execution.

     --limit <unsigned integer> [-u]
	    [LIMIT]  Specifies the limit in bytes at which  all  memory  alloca-
	    tions  should fail if the total allocated memory should increase be-
	    yond this.

     --list [-i]
	    [LIST]  Specifies that a context listing should  be  shown	for  any
	    relevant  source  files that are associated with any warnings or er-
	    rors when they occur.

     --log-all [-L]
	    [LOGALL]	Equivalent   to   the	--log-allocs,	 --log-reallocs,
	    --log-frees and --log-memory options specified together.

     --log-allocs
	    [LOGALLOCS]   Specifies that all memory allocations are to be logged
	    and sent to the log file.

     --log-file <string> [-l]
	    [LOGFILE]  Specifies an alternative file in which to place all diag-
	    nostics from the mpatrol library.

     --log-frees
	    [LOGFREES]	Specifies that all memory deallocations are to be logged
	    and sent to the log file.

     --log-memory
	    [LOGMEMORY]  Specifies that all memory operations are to  be  logged
	    and sent to the log file.

     --log-reallocs
	    [LOGREALLOCS]   Specifies  that  all  memory reallocations are to be
	    logged and sent to the log file.

     --medium-bound <unsigned integer>
	    [MEDIUMBOUND]  Specifies the limit in bytes up to which memory allo-
	    cations should be classified as  medium  allocations  for  profiling
	    purposes.

     --no-free <unsigned integer> [-n]
	    [NOFREE]   Specifies  that a number of recently-freed memory alloca-
	    tions should be prevented from being returned  to  the  free  memory
	    pool.

     --no-protect [-N]
	    [NOPROTECT]   Specifies  that  the	mpatrol  library's internal data
	    structures should not be made read-only after every  memory  alloca-
	    tion, reallocation or deallocation.

     --oflow-byte <unsigned integer> [-o]
	    [OFLOWBYTE]   Specifies an 8-bit byte pattern with which to fill the
	    overflow buffers of all memory allocations.

     --oflow-size <unsigned integer> [-O]
	    [OFLOWSIZE]  Specifies the size in bytes to  use  for  all	overflow
	    buffers, which must be a power of two.

     --oflow-watch [-w]
	    [OFLOWWATCH]   Specifies  that  watch point areas should be used for
	    overflow buffers rather than filling with the overflow byte.

     --page-alloc-lower [-b]
	    [PAGEALLOC=LOWER]  Specifies that each individual memory  allocation
	    should  occupy  at	least  one  page of virtual memory and should be
	    placed at the lowest point within these pages.

     --page-alloc-upper [-B]
	    [PAGEALLOC=UPPER]  Specifies that each individual memory  allocation
	    should  occupy  at	least  one  page of virtual memory and should be
	    placed at the highest point within these pages.

     --preserve [-v]
	    [PRESERVE]	Specifies that any reallocated or freed  memory  alloca-
	    tions should preserve their original contents.

     --prof [-p]
	    [PROF]  Specifies that all memory allocations are to be profiled and
	    sent to the profiling output file.

     --prof-file <string> [-P]
	    [PROFFILE]	Specifies an alternative file in which to place all mem-
	    ory allocation profiling information from the mpatrol library.

     --prog-file <string> [-r]
	    [PROGFILE]	 Specifies  an alternative filename with which to locate
	    the executable file containing the program's symbols.

     --read-env [-I]
	    Reads and passes through the contents of the  MPATROL_OPTIONS  envi-
	    ronment  variable.	 Such  contents will be placed before any of the
	    options resulting from mpatrol command line options so that they can
	    be overridden and will only be parsed by the  mpatrol  library,  not
	    the mpatrol command.

     --realloc-stop <unsigned integer> [-R]
	    [REALLOCSTOP]   Specifies  an  allocation index at which to stop the
	    program when a memory allocation is being reallocated.

     --safe-signals [-G]
	    [SAFESIGNALS]  Instructs the library to  save  and	replace  certain
	    signal  handlers during the execution of library code and to restore
	    them afterwards.

     --show-all [-S]
	    [SHOWALL]  Equivalent to the --show-free,  --show-freed,  --show-un-
	    freed, --show-map and --show-symbols options specified together.

     --show-env [-E]
	    Displays  the  contents of the MPATROL_OPTIONS environment variable.
	    This will be shown after all of the other command line options  have
	    been  processed  and  will	prevent the specified command from being
	    run.

     --show-free
	    [SHOWFREE]	Specifies that a summary  of  all  of  the  free  memory
	    blocks should be displayed at the end of program execution.

     --show-freed
	    [SHOWFREED]  Specifies that a summary of all of the freed memory al-
	    locations should be displayed at the end of program execution.

     --show-map
	    [SHOWMAP]	Specifies that a memory map of the entire heap should be
	    displayed at the end of program execution.

     --show-symbols
	    [SHOWSYMBOLS]  Specifies that a summary of all of the function  sym-
	    bols  read from the program's executable file should be displayed at
	    the end of program execution.

     --show-unfreed
	    [SHOWUNFREED]  Specifies that a summary of all of the unfreed memory
	    allocations should be displayed at the end of program execution.

     --small-bound <unsigned integer>
	    [SMALLBOUND]  Specifies the limit in bytes up to which memory  allo-
	    cations should be classified as small allocations for profiling pur-
	    poses.

     --threads [-j]
	    Specifies  that  the program to be run is multithreaded if the --dy-
	    namic option is used.  This option is required if the  multithreaded
	    version  of  the  mpatrol library should be preloaded instead of the
	    normal version.

     --trace [-t]
	    Specifies that all memory allocations are to be traced and	sent  to
	    the tracing output file.

     --trace-file <string> [-T]
	    Specifies  an  alternative file in which to place all memory alloca-
	    tion tracing information from the mpatrol library.

     --unfreed-abort <unsigned integer> [-U]
	    [UNFREEDABORT]  Specifies the minimum number of unfreed  allocations
	    at which to abort the program just before program termination.

     --use-debug [-g]
	    [USEDEBUG]	 Specifies  that  any  debugging information in the exe-
	    cutable file should be used to obtain additional source-level infor-
	    mation.

     --use-mmap [-m]
	    [USEMMAP]  Specifies that the library should use mmap()  instead  of
	    sbrk() to allocate user memory.

     --version [-V]
	    Displays the version number of the mpatrol command.

SEE ALSO
     mprof(1),	mptrace(1),  mleak(1), mpsym(1), mpedit(1), hexwords(1), libmpa-
     trol(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 		      MPATROL(1)
home | help