7.2 Logging and tracing

If you would like to see a complete log of all of the memory allocations, reallocations and deallocations performed by your program, use the `LOGALL' option. This provides detailed tracing for each of the mpatrol library functions, and a full description of the format of such tracing is given in Example 1 (see section 16.1 Getting started). Alternatively, you may select one or more types of functions to be traced using the `LOGALLOCS', `LOGREALLOCS', `LOGFREES' and `LOGMEMORY' options if you feel that the log file is too large when `LOGALL' is used. By default all diagnostics from the mpatrol library get sent to `mpatrol.log' in the current directory, but this can be changed using the `LOGFILE' option. In fact, you can also specify a directory where all log files from the mpatrol library will get placed by setting the LOGDIR environment variable.

On systems that support it, every log entry also contains a call stack traceback that may also include the names of the symbols that appear on the call stack. If the object file access library that mpatrol was built with has support for reading line number tables from object files then the `USEDEBUG' option will also try to determine the file name and line number for each entry in the call stack, but only if the object files contain the relevant debugging information. This information will only be available before program termination and so any call stack tracebacks that appear after the library summary will not be displayed with their corresponding file name and line number. This option will also slow down program execution since a search through the line number tables will have to be made every time a call stack is displayed. Alternatively, the mpsym command may be used to process an mpatrol log file with a debugger in order to obtain symbol names and source level information for any call stacks.

Because the alloca(), strdupa() and strndupa() functions automatically free their allocations when the calling function returns, the log entries for these types of memory allocation are slightly different. The actual memory allocation will have an entry similar to malloc(), etc., but the memory deallocation will be marked as being done by alloca() and will occur at the next call to an mpatrol library function after the calling function has returned. However, any such allocations that are explicitly deallocated with the dealloca() function will be marked as being done by dealloca().

The mpatrol library will always try to display as much useful information as possible in this log file, and will always display a summary of library settings and statistics when your program terminates successfully. If you don't get this then your program did not call exit() and either called abort() or was terminated by the operating system instead. In such cases, either use a debugger to see where your program crashed or use the `LOGALL' option to see the last successful library call in the log file so that you have a rough idea of where your program crashed.

It is also possible to get mpatrol to write more summary information to the log file after it writes out its settings and statistics at program termination. Use the `SHOWFREED' and `SHOWUNFREED' options to display a list of freed and unfreed memory allocations. The former will only be displayed if the `NOFREE' option is used, but the latter can be useful for detecting memory leaks. The `SHOWFREE' option can be used to display a summary of any free memory blocks.

The `SHOWMAP' option will display a memory map of the heap that was valid when the process terminated, and the `SHOWSYMBOLS' option will display any symbolic information that the mpatrol library managed to obtain from any executable files and libraries that were relevant to the program being tested. All of the above five options can be selected with the `SHOWALL' option.

For the purpose of detecting memory leaks, you can instruct the mpatrol library to automatically log every memory allocation event into a special hash table called the leak table with the `LEAKTABLE' option. This option will then cause the mpatrol library to display a sorted summary of all of the memory leaks or unfreed memory allocations to the mpatrol log file when the program terminates. The leak table is indexed by the source file and line number where memory allocation events occur, but if this information is not available then either the function name or the return address will be used instead. Note that this option differs from the `SHOWUNFREED' option in that it will summarise where the leaks came from rather than show the full details of each individual unfreed memory allocation.

Because the log file can contain verbose information about memory allocations, reallocations, deallocations and operations, it can end up being too large if all such information is being logged for a large program. To get around this, it is possible to trace all memory allocation, reallocation and deallocation events in a concise way, to be stored in a separate file for later processing by the mptrace command. By default, no such tracing is performed but it can be enabled with the `TRACE' option. The default tracing output file is `mpatrol.trace', but this can be changed using the `TRACEFILE' option. As with the `LOGFILE' option, you can also specify a directory where all tracing output files from the mpatrol library will get placed by setting the TRACEDIR environment variable.