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

FreeBSD Manual Pages

  
 
  

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	profiling  output  filename  is	mpatrol.%n.out and the default
       tracing output filename 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
       library 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  pre-
	      fill newly-allocated memory.

       --alloc-stop <unsigned integer> [-A]
	      [ALLOCSTOP]   Specifies an allocation index at which to stop the
	      program 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 boundaries 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
	      memory allocations, which	must be	a power	of two.

       --dynamic [-d]
	      Specifies	 that  programs	which were not linked with the mpatrol
	      library 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  li-
	      braries 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 errors	when they occur.

       --fail-freq <unsigned integer> [-q]
	      [FAILFREQ]   Specifies the frequency at which all	memory alloca-
	      tions 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 pre-
	      fill newly-freed memory.

       --free-stop <unsigned integer> [-F]
	      [FREESTOP]  Specifies an allocation index	at which to  stop  the
	      program 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
	      allocations should be classified as large	allocations  for  pro-
	      filing purposes.

       --leak-table
	      [LEAKTABLE]  Specifies  that  the	leak table should be automati-
	      cally used and a leak table summary should be displayed  at  the
	      end of program execution.

       --limit <unsigned integer> [-u]
	      [LIMIT]	Specifies the limit in bytes at	which all memory allo-
	      cations should fail if the total	allocated  memory  should  in-
	      crease beyond this.

       --list [-i]
	      [LIST]  Specifies	that a context listing should be shown for any
	      relevant source files that are associated	with any  warnings  or
	      errors 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
	      diagnostics 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
	      allocations should be classified as medium allocations for  pro-
	      filing purposes.

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

       --no-protect [-N]
	      [NOPROTECT]   Specifies that the mpatrol library's internal data
	      structures should	not be made read-only after every memory allo-
	      cation, 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 alloca-
	      tion  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 alloca-
	      tion  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 allo-
	      cations 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
	      memory  allocation  profiling  information  from the mpatrol li-
	      brary.

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

       --read-env [-I]
	      Reads and	passes through the contents of the MPATROL_OPTIONS en-
	      vironment	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 re-
	      store them afterwards.

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

       --show-env [-E]
	      Displays the contents of the MPATROL_OPTIONS  environment	 vari-
	      able.   This  will  be shown after all of	the other command line
	      options have been	processed and will prevent the specified  com-
	      mand 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
	      allocations 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
	      symbols  read  from the program's	executable file	should be dis-
	      played 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 ex-
	      ecution.

       --small-bound <unsigned integer>
	      [SMALLBOUND]  Specifies the limit	in bytes up  to	 which	memory
	      allocations  should  be classified as small allocations for pro-
	      filing purposes.

       --threads [-j]
	      Specifies	that the program to be run  is	multithreaded  if  the
	      --dynamic	option is used.	 This option is	required if the	multi-
	      threaded version of the mpatrol library should be	preloaded  in-
	      stead 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 allo-
	      cation tracing information from the mpatrol library.

       --unfreed-abort <unsigned integer> [-U]
	      [UNFREEDABORT]   Specifies the minimum number of unfreed alloca-
	      tions at which to	abort the program just before program termina-
	      tion.

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

       --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), libm-
       patrol(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			    MPATROL(1)

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

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

home | help