Environment - mpatrol

Next: Options, Previous: Functions, Up: Top

Appendix B Environment

The library can read certain options at run-time from an environment variable called MPATROL_OPTIONS. This variable must contain one or more valid option keywords from the list below and must be no longer than 1024 characters in length. If MPATROL_OPTIONS is unset or empty then the default settings will be used.

The syntax for options specified within the MPATROL_OPTIONS environment variable is `OPTION' or `OPTION=VALUE', where `OPTION' is a keyword from the list below and `VALUE' is the setting for that option. If `VALUE' is numeric then it may be specified using binary, octal, decimal or hexadecimal notation, with binary notation beginning with either `0b' or `0B'. If `VALUE' is a character string containing spaces then it may be quoted using double quotes. No whitespace may appear between the `=' sign, but whitespace must appear between different options. Note that option keywords can be given in lowercase as well as uppercase, or a mixture of both.

ALLOCBYTE=<unsigned-integer>: Specifies an 8-bit byte pattern with which to prefill newly-allocated memory. This can be used to detect the use of memory which has not been initialised after allocation. Note that this setting will not affect memory allocated with calloc() or recalloc() as these functions always prefill allocated memory with an 8-bit byte pattern of zero. Default value: ALLOCBYTE=0xFF.
ALLOCSTOP=<unsigned-integer>: Specifies an allocation index at which to stop the program when it is being allocated. When the number of memory allocations reaches this number the program will be halted, and its state may be examined at that point by using a suitable debugger. Note that this setting will be ignored if its value is zero. Default value: ALLOCSTOP=0.
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. This option is provided for circumstances where it is desirable for the memory operation to be performed, regardless of whether it is erroneous or not.
AUTOSAVE=<unsigned-integer>: Specifies the frequency at which to periodically write the profiling data to the profiling output file. When the total number of profiled memory allocations and deallocations is a multiple of this number then the current profiling information will be written to the profiling output file. This option can be used to instruct the mpatrol library to dump out any profiling information just before a fatal error occurs in a program, for example. Note that this setting will be ignored if its value is zero. Default value: AUTOSAVE=0.
CHECK=<unsigned-range>: Specifies a range of allocation indices at which to check the integrity of free memory and overflow buffers. The range must be specified as no more than two unsigned integers separated by a dash, followed by an optional forward slash and an unsigned integer specifying an event checking frequency. If numbers on either the left side or the right side of the dash are omitted then they will be assumed to be `0' and infinity respectively. A value of `0' on its own indicates that no such checking will ever be performed. This option can be used to speed up the execution speed of the library at the expense of checking. Default value: CHECK=0.
CHECKALL: Equivalent to the CHECKALLOCS, CHECKREALLOCS, CHECKFREES and CHECKMEMORY options specified together.
CHECKALLOCS: Checks that no attempt is made to allocate a block of memory of size zero. A warning will be issued for every such case.
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. This option only has an effect on UNIX platforms, but should not be used in multithreaded programs if each thread has a different process identifier.
CHECKFREES: Checks that no attempt is made to deallocate a `NULL' pointer. A warning will be issued for every such case.
CHECKMEMORY: Checks that no attempt is made to perform a zero-length memory operation or a memory operation on a `NULL' pointer.
CHECKREALLOCS: Checks that no attempt is made to reallocate a `NULL' pointer or resize an existing block of memory to size zero. Warnings will be issued for every such case.
DEFALIGN=<unsigned-integer>: Specifies the default alignment for general-purpose memory allocations, which must be a power of two (and will be rounded up to the nearest power of two if it is not). The default alignment for a particular system is calculated at run-time.
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. Only diagnostics which occur at source lines in the program will be affected and only then if they contain source-level information. This option is currently only available on UNIX platforms as it makes use of the mpedit command. It also overrides the behaviour of the LIST option and affects the behaviour of the __mp_view() function.
FAILFREQ=<unsigned-integer>: Specifies the frequency at which all memory allocations will randomly fail. For example, a value of `10' will mean that roughly 1 in 10 memory allocations will fail, but a value of `0' will disable all random failures. This option can be useful for stress-testing an application. Default value: FAILFREQ=0.
FAILSEED=<unsigned-integer>: Specifies the random number seed which will be used when determining which memory allocations will randomly fail. A value of `0' will instruct the library to pick a random seed every time it is run. Any other value will mean that the random failures will be the same every time the program is run, but only as long as the seed stays the same. Default value: FAILSEED=0.
FREEBYTE=<unsigned-integer>: Specifies an 8-bit byte pattern with which to prefill newly-freed memory. This can be used to detect the use of memory which has just been freed. It is also used internally to ensure that freed memory has not been overwritten. Note that the freed memory may be reused the next time a block of memory is allocated and so once memory has been freed its contents are not guaranteed to remain the same as the specified byte pattern. Default value: FREEBYTE=0x55.
FREESTOP=<unsigned-integer>: Specifies an allocation index at which to stop the program when it is being freed. When the memory allocation with the specified allocation index is to be freed the program will be halted, and its state may be examined at that point using a suitable debugger. Note that this setting will be ignored if its value is zero. Default value: FREESTOP=0.
HELP: Displays a quick-reference option summary to the stderr file stream.
LARGEBOUND=<unsigned-integer>: Specifies the limit in bytes up to which memory allocations should be classified as large allocations for profiling purposes. This limit must be greater than the small and medium bounds. Default value: LARGEBOUND=2048.
LEAKTABLE: Specifies that the leak table should be automatically used and a leak table summary should be displayed at the end of program execution. The summary shows a flat profile of all unfreed memory allocations since the start of the program, or since the last call to __mp_clearleaktable() if that function was called.
LIMIT=<unsigned-integer>: Specifies the limit in bytes at which all memory allocations should fail if the total allocated memory should increase beyond this. This can be used to stress-test software to see how it behaves in low memory conditions. The internal memory used by the library itself will not be counted as part of the total heap size, but on some systems there may be a small amount of memory required to initialise the library itself. Note that this setting will be ignored if its value is zero. Default value: LIMIT=0.
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. Only diagnostics which occur at source lines in the program will be affected and only then if they contain source-level information. This option is currently only available on UNIX platforms as it makes use of the mpedit command. It also overrides the behaviour of the EDIT option and affects the behaviour of the __mp_view() function.
LOGALL: Equivalent to the LOGALLOCS, LOGREALLOCS, LOGFREES and LOGMEMORY options specified together.
LOGALLOCS: Specifies that all memory allocations are to be logged and sent to the log file. Note that any memory allocations made internally by the library will not be logged.
LOGFILE=<string>: Specifies an alternative file in which to place all diagnostics from the mpatrol library. If the LOGDIR environment variable is set and the specified file does not contain a path component in its filename then the log file will be located in the directory specified in LOGDIR. A filename of `stderr' will send all diagnostics to the stderr file stream and a filename of `stdout' will do the equivalent with the stdout file stream. Note that if a problem occurs while opening the log file or if any diagnostics require to be displayed before the log file has had a chance to be opened then they will be sent to the stderr file stream. Default value: LOGFILE=mpatrol.log or LOGFILE=%n.%p.log if the LOGDIR environment variable is set.
LOGFREES: Specifies that all memory deallocations are to be logged and sent to the log file. Note that any memory deallocations made internally by the library will not be logged.
LOGMEMORY: Specifies that all memory operations are to be logged and sent to the log file. These operations will be made by calls to functions such as memset() and memcpy(). Note that any memory operations made internally by the library will not be logged.
LOGREALLOCS: Specifies that all memory reallocations are to be logged and sent to the log file. Note that any memory reallocations made internally by the library will not be logged.
MEDIUMBOUND=<unsigned-integer>: Specifies the limit in bytes up to which memory allocations should be classified as medium allocations for profiling purposes. This limit must be greater than the small bound but less than the large bound. Default value: MEDIUMBOUND=256.
NOFREE=<unsigned-integer>: Specifies that a number of recently-freed memory allocations should be prevented from being returned to the free memory pool. Such freed memory allocations will then be flagged as freed and can be used by the library to provide better diagnostics. If the size of the freed queue is specified as zero then all freed memory will be immediately reused by the mpatrol library. Note that if this option is given a non-zero value then the mpatrol library will always force a memory reallocation to return a pointer to newly-allocated memory, but the expand() function will never be affected by this option. Default value: NOFREE=0.
NOPROTECT: Specifies that the mpatrol library's internal data structures should not be made read-only after every memory allocation, reallocation or deallocation. This may significantly speed up execution but this will be at the expense of less safety if the program accidentally overwrites some of the library's internal data structures. Note that this option has no effect on systems that do not support memory protection.
OFLOWBYTE=<unsigned-integer>: Specifies an 8-bit byte pattern with which to fill the overflow buffers of all memory allocations. This is used internally to ensure that nothing has been written beyond the beginning or the end of a block of allocated memory. Note that this setting will only have an effect if the OFLOWSIZE option is in use. Default value: OFLOWBYTE=0xAA.
OFLOWSIZE=<unsigned-integer>: Specifies the size in bytes to use for all overflow buffers, which must be a power of two (and will be rounded up to the nearest power of two if it is not). This is used internally to ensure that nothing has been written beyond the beginning or the end of a block of allocated memory. Note that this setting specifies the size for only one of the overflow buffers given to each memory allocation; the other overflow buffer will have an identical size. No overflow buffers will be used if this setting is zero. Default value: OFLOWSIZE=0.
OFLOWWATCH: Specifies that watch point areas should be used for overflow buffers rather than filling with the overflow byte. This can significantly reduce the speed of program execution. Note that this option has no effect on systems that do not support watch point areas.
PAGEALLOC=<LOWER|UPPER>: Specifies that each individual memory allocation should occupy at least one page of virtual memory and should be placed at the lowest or highest point within these pages. This allows the library to place an overflow buffer of one page on either side of every memory allocation and write-protect these pages as well as all free and freed memory. Note that this option has no effect on systems that do not support memory protection, and is disabled by default on other systems as it can slow down the speed of program execution.
PRESERVE: Specifies that any reallocated or freed memory allocations should preserve their original contents. This option must be used with the NOFREE option and has no effect otherwise.
PROF: Specifies that all memory allocations and deallocations are to be profiled and sent to the profiling output file. Memory reallocations are treated as a memory deallocation immediately followed by a memory allocation.
PROFFILE=<string>: Specifies an alternative file in which to place all memory allocation profiling information from the mpatrol library. If the PROFDIR environment variable is set and the specified file does not contain a path component in its filename then the profiling output file will be located in the directory specified in PROFDIR. A filename of `stderr' will send this information to the stderr file stream and a filename of `stdout' will do the equivalent with the stdout file stream. Note that if a problem occurs while opening the profiling output file then the profiling information will not be output. Default value: PROFFILE=mpatrol.out or PROFFILE=%n.%p.out if the PROFDIR environment variable is set.
PROGFILE=<string>: Specifies an alternative filename with which to locate the executable file containing the program's symbols. On most systems, the library will automatically be able to determine this filename, but on a few systems this option may have to be used before any or all symbols can be read.
REALLOCSTOP=<unsigned-integer>: Specifies a reallocation index at which to stop the program when a memory allocation is being reallocated. If the ALLOCSTOP option is non-zero then the program will be halted when the allocation matching that allocation index is reallocated the specified number of times. Otherwise the program will be halted the first time any allocation is reallocated the specified number of times. Note that this setting will be ignored if its value is zero. Default value: REALLOCSTOP=0.
SAFESIGNALS: Instructs the library to save and replace certain signal handlers during the execution of library code and to restore them afterwards. This was the default behaviour in version 1.0 of the mpatrol library and was changed since some memory-intensive programs became very hard to interrupt using the keyboard, thus giving the impression that the program or system had hung.
SHOWALL: Equivalent to the SHOWFREE, SHOWFREED, SHOWUNFREED, SHOWMAP and SHOWSYMBOLS options specified together.
SHOWFREE: Specifies that a summary of all of the free memory blocks should be displayed at the end of program execution. This step will not be performed if an abnormal termination occurs or if there were no free memory blocks.
SHOWFREED: Specifies that a summary of all of the freed memory allocations should be displayed at the end of program execution. This option must be used in conjunction with the NOFREE option and this step will not be performed if an abnormal termination occurs or if there were no freed allocations.
SHOWMAP: Specifies that a memory map of the entire heap should be displayed at the end of program execution. This step will not be performed if an abnormal termination occurs or if the heap is empty.
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. This step will not be performed if an abnormal termination occurs or if no symbols could be read from the executable file.
SHOWUNFREED: Specifies that a summary of all of the unfreed memory allocations should be displayed at the end of program execution. This step will not be performed if an abnormal termination occurs or if there are no unfreed allocations. Note that any marked memory allocations will not be listed.
SMALLBOUND=<unsigned-integer>: Specifies the limit in bytes up to which memory allocations should be classified as small allocations for profiling purposes. This limit must be greater than zero but less than the medium and large bounds. Default value: SMALLBOUND=32.
TRACE: Specifies that all memory allocations, reallocations and deallocations are to be traced and sent to the tracing output file.
TRACEFILE=<string>: Specifies an alternative file in which to place all memory allocation tracing information from the mpatrol library. If the TRACEDIR environment variable is set and the specified file does not contain a path component in its filename then the tracing output file will be located in the directory specified in TRACEDIR. A filename of `stderr' will send this information to the stderr file stream and a filename of `stdout' will do the equivalent with the stdout file stream. Note that if a problem occurs while opening the tracing output file then the tracing information will not be output. Default value: TRACEFILE=mpatrol.trace or TRACEFILE=%n.%p.trace if the TRACEDIR environment variable is set.
UNFREEDABORT=<unsigned-integer>: Specifies the minimum number of unfreed allocations at which to abort the program just before program termination. A summary of all the allocations will be displayed on the standard error file stream before aborting. This option may be handy for use in batch tests as it can force tests to fail if they do not free up a minimum number of memory allocations, although marked allocations will not be considered as unfreed allocations. Note that this setting will be ignored if its value is zero. Default value: UNFREEDABORT=0.
USEDEBUG: Specifies that any debugging information in the executable file should be used to obtain additional source-level information. This option will only have an effect if the executable file contains a compiler-generated line number table and will be ignored if the mpatrol library was built to support an object file access library that cannot read line tables from object files. Note that this option will slow down program execution, use up more system memory and may leave unaccounted unfreed memory allocations at program termination.
USEMMAP: Specifies that the library should use mmap() instead of sbrk() to allocate user memory on UNIX platforms. This option should be used if there are problems when using the mpatrol library in combination with another malloc library which uses sbrk() to allocate its memory. Memory internal to the mpatrol library is allocated with mmap() on systems where it is supported in order to segregate it from user memory, and this behaviour is reversed with the USEMMAP option. It is ignored on systems that do not support the mmap() system call. Note that some UNIX systems require this option in order for the mpatrol library to be able to perform memory protection with the mprotect() system call.