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)¹. If it was built with FORMAT=FORMAT_BFD support then it must be told to preload the GNU BFD access libraries (normally libbfd.so, libiberty.so and libintl.so)². 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