Appendix C Options

A utility program called mpatrol is provided to run commands that have been linked with 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.

Alternatively, the log file, profiling output file and tracing output file names can contain `%p', which will be replaced with the name of the program being executed without the directory components. If the executable filename could not be determined or was not set then it will be replaced with `mpatrol'. A similar replacement character sequence is `%f', which will be replaced by the pathname of the program being executed, with all path separation characters replaced by underscores.

The current date can be entered into such filenames through the use of the `%d' character sequence, which will be replaced with the date in the form `YYYYMMDD'. The current time can be added with `%t', which will be replaced with the time in the form `HHMMSS'. If the date or time could not be determined, these will be replaced with `today' and `now' respectively.

All of the following options (except --dynamic, --help, --read-env, --show-env, --threads and --version) correspond to their listed mpatrol library option (see Environment). Note that some of these options have a one character equivalent option that can be used for brevity. The list of one character options can be viewed with the --help option or viewed in the UNIX manual pages. Such options are parsed on the command line in a similar way to the UNIX function getopt().

--alloc-byte <unsigned-integer>

[ALLOCBYTE] Specifies an 8-bit byte pattern with which to prefill newly-allocated memory.

--alloc-stop <unsigned-integer>

[ALLOCSTOP] Specifies an allocation index at which to stop the program when it is being allocated.

--allow-oflow

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

[AUTOSAVE] Specifies the frequency at which to periodically write the profiling data to the profiling output file.

--check <unsigned-range>

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

--check-all

[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 or a 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>

[DEFALIGN] Specifies the default alignment for general-purpose memory allocations, which must be a power of two.

--dynamic

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

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

[FAILFREQ] Specifies the frequency at which all memory allocations will randomly fail.

--fail-seed <unsigned-integer>

[FAILSEED] Specifies the random number seed which will be used when determining which memory allocations will randomly fail.

--free-byte <unsigned-integer>

[FREEBYTE] Specifies an 8-bit byte pattern with which to prefill newly-freed memory.

--free-stop <unsigned-integer>

[FREESTOP] Specifies an allocation index at which to stop the program when it is being freed.

--help

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>

[LIMIT] Specifies the limit in bytes at which all memory allocations should fail if the total allocated memory should increase beyond this.

--list

[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

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

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

[NOFREE] Specifies that a number of recently-freed memory allocations should be prevented from being returned to the free memory pool.

--no-protect

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

[OFLOWBYTE] Specifies an 8-bit byte pattern with which to fill the overflow buffers of all memory allocations.

--oflow-size <unsigned-integer>

[OFLOWSIZE] Specifies the size in bytes to use for all overflow buffers, which must be a power of two.

--oflow-watch

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

--page-alloc-lower

[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

[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

[PRESERVE] Specifies that any reallocated or freed memory allocations should preserve their original contents.

--prof

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

--prof-file <string>

[PROFFILE] Specifies an alternative file in which to place all memory allocation profiling information from the mpatrol library.

--prog-file <string>

[PROGFILE] Specifies an alternative filename with which to locate the executable file containing the program's symbols.

--read-env

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>

[REALLOCSTOP] Specifies an allocation index at which to stop the program when a memory allocation is being reallocated.

--safe-signals

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

--show-all

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

--show-env

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

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

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

--trace-file <string>

[TRACEFILE] Specifies an alternative file in which to place all memory allocation tracing information from the mpatrol library.

--unfreed-abort <unsigned-integer>

[UNFREEDABORT] Specifies the minimum number of unfreed allocations at which to abort the program just before program termination.

--use-debug

[USEDEBUG] Specifies that any debugging information in the executable file should be used to obtain additional source-level information.

--use-mmap

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

--version

Displays the version number of the mpatrol command.