9.1 The mpatrol command

A command is provided with the mpatrol distribution which can run programs that have been linked with the mpatrol library, using a combination of mpatrol options that can be set via the command line. Most of these options map directly onto their equivalent environment variable settings and exist mainly so that the user does not have to manually change the MPATROL_OPTIONS environment variable.

The main option that is the exception to this is the `--dynamic' option, which can be used to run a program under the control of the mpatrol library, even if it wasn't originally linked with the mpatrol library. This can only be done on systems that support dynamic linking and where the dynamic linker recognises the LD_PRELOAD or _RLD_LIST environment variables. Even then, it can only be used when the program that is being run has been dynamically linked with the system C library, rather than statically linked.

The reason for all of these limitations is that some SVR4 UNIX platforms have a special feature in the dynamic linker which can be told to override the symbols from one shared library using the symbols from another shared library at run-time. In this case, it involves replacing the symbols for malloc(), etc., in the system C library with the mpatrol versions, but only if they were marked as undefined in the original executable file and would therefore have to have been loaded from `libc.so'.

However, if a program qualifies for use with the `--dynamic' option, it means that you can trace all of its dynamic memory allocations as well as running it with any of the mpatrol library's debugging options. This is mainly a toy feature which allows you to view and manipulate the dynamic memory allocations of programs that you don't have the source for, but in theory it could be quite useful if you need to debug a previously released executable and are unable to recompile or relink it. Note that if the program being run is multithreaded then you must add the `--threads' option as well.

Note that the mpatrol command must be set up to use the correct object file format access libraries that are required for your system if you wish to use the `--dynamic' option. If the mpatrol library was built with FORMAT=FORMAT_COFF or FORMAT=FORMAT_XCOFF support then it must be told to preload the COFF access library (normally `libld.so'). If it was built with FORMAT=FORMAT_ELF32 or FORMAT=FORMAT_ELF64 support then it must be told to preload the ELF access library (normally `libelf.so')(31). If it was built with FORMAT=FORMAT_BFD support then it must be told to preload the GNU BFD access libraries (normally `libbfd.so' and `libiberty.so')(32). However, if these libraries only exist on your system in archive form then you must build `libmpatrol.so' with these extra libraries incorporated into it so that there are no dependencies on them at run-time. However, there may well be problems if the resulting shared library contains position-dependent code from the archive libraries you incorporated. The only way to find out is for you to try it and see.

If you have access to the GNU linker on your system then there may be a way to convert archive libraries into shared libraries if position-independent code is not necessarily required for building shared libraries on your system. If you use the `--whole-archive' and `--shared' linker options then the GNU linker will read the entire contents of one or more archive libraries before writing out a shared library. All going well, you should be able to use the new shared library in conjunction with the `--dynamic' mpatrol option.

In order to build a shared version of the mpatrol library with embedded object file format access libraries, you must first modify the `Makefile' you would normally use to build the mpatrol library. At the lines where the linker is invoked to build the shared library, you must explicitly add any object file format access libraries that you want to use at the end of the linker command line. This ensures that all references to such libraries will be resolved at link time rather than run time. You must then edit the file `src/config.h' and remove all of the libraries that you embedded from the definitions of the MP_PRELOAD_LIBS and `MP_PRELOADMT_LIBS' preprocessor macros. Finally, rebuild the shared version of the mpatrol library and the mpatrol command and see if your efforts were worth it.

Because the mpatrol command sets the MPATROL_OPTIONS environment variable for each of the programs it runs, it does not affect the value of the environment variable for the current process (except on AmigaOS and Netware where all processes share the same environment). However, if you wish to use the mpatrol command to set MPATROL_OPTIONS in the current process environment then you can use its `--show-env' option to help you do so. This option will apply all of the mpatrol command line options to the MPATROL_OPTIONS environment variable and then display its value on the standard output without actually running any programs. You can then manually set the environment variable with the output from the mpatrol command.

If you wish the MPATROL_OPTIONS environment variable to be set in the current shell process automatically with the mpatrol command then you must use some shell trickery. The following script excerpts can be found in `extra/.profile', `extra/.cshrc' and `extra/.gdbinit' and can be inserted into your ksh/bash, csh/tcsh and gdb configuration files respectively. They each provide the mallopt command, which takes mpatrol command options and sets the MPATROL_OPTIONS environment variable in the current shell or debugger process.

# mallopt for ksh/bash function mallopt() { export MPATROL_OPTIONS=`mpatrol --show-env "$@"` echo "$MPATROL_OPTIONS" } # mallopt for csh/tcsh alias mallopt 'setenv MPATROL_OPTIONS "`mpatrol --show-env \!*`"; echo "$MPATROL_OPTIONS"' # mallopt for gdb define mallopt printf "Enter mpatrol library options: " shell read arg; echo set environment MPATROL_OPTIONS `mpatrol --show-env $arg` >/tmp/mpatrol.gdb source /tmp/mpatrol.gdb shell rm -f /tmp/mpatrol.gdb show environment MPATROL_OPTIONS end document mallopt Sets mpatrol library options in the current process environment. end