9.3 The mpsym command

Another utility program that is provided is called mpsym, which is used to parse a log file produced by the mpatrol library and uses a debugger to append symbol names and source level information to code addresses in stack tracebacks. This should be used if the `USEDEBUG' option is not supported on a particular platform or does not work properly with a specific program. It will replace all existing symbols and source level information associated with the stack tracebacks in the mpatrol log file and will display the resulting log file on the standard output file stream.

The first argument to mpsym must be the filename of the executable file that produced the mpatrol log file but if it is omitted then mpsym will use `a.out' as the name of the executable file to use. The mpsym command will read the symbol table and debugging sections from this file in order to map the code addresses that appear in the mpatrol log file into symbol names and source level information. If the executable file does not contain a symbol table then no symbol names will be available and if it does not contain the appropriate debugging sections then no source level information will be available either. Obviously, if the executable file is not the same as the one that created the mpatrol log file then the final output will be wrong.

The second argument to mpsym must be a valid mpatrol log filename but if it is omitted then mpsym will use `mpatrol.log' as the name of the log file to use, or `progfile.log' if it can't find that. The mpsym command makes two passes over the log file so the file must be randomly-accessable. Note also that the mpsym command supports the `--help' and `--version' options in common with the other mpatrol command line tools.

If the mpatrol library cannot determine the name of a symbol for display in the log file then it will mark the symbol as `???'. If the debugger that is being used by mpsym also has problems determining the name of the symbol then you can pass the `--skip' option to mpsym to instruct it to skip any symbols marked as `???' in the log file.

The mpsym command currently uses gdb as the debugger with which to obtain the additional information about the code addresses in the mpatrol log file. It also makes use of several UNIX text processing commands, including perl if it is installed, in order to extract information from the debugger's output and from the log file. As a result, the mpsym command is only likely to work on UNIX platforms or on systems which have the necessary commands installed.