mpatrol - runs programs using the mpatrol library

mpatrol [options] <command> [arguments]

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.

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 prefill 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 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 errors 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 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 profiling purposes.

--leak-table

[LEAKTABLE] Specifies that the leak table should be automatically 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 allocations should fail if the total allocated memory should increase 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 profiling purposes.

--no-free <unsigned integer> [-n]

[NOFREE] Specifies that a number of recently-freed memory allocations 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 allocation, 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 allocations 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 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 environment 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-unfreed, --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 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 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 allocations should be classified as small allocations for profiling purposes.

--threads [-j]

Specifies that the program to be run is multithreaded if the --dynamic 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 allocation 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 executable 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.

mprof(1), mptrace(1), mleak(1), mpsym(1), mpedit(1), hexwords(1), libmpatrol(3), libmpalloc(3).

The mpatrol manual and reference card.

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

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

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