Linking Your Application With the Agent
MemoryScape puts its heap agent between your program and its heap library which allows the agent to intercept the calls that your program makes to this library. After it intercepts the call, it checks the call for errors and then sends it on to the library so that it can be processed. The MemoryScape agent does not replace standard memory functions; it just monitors what they do. For more information, see “Behind the Scenes” in the introduction to Debugging Memory Problems with MemoryScape.
In most cases, MemoryScape arranges for the heap agent to be loaded automatically when it starts your program. In some cases, however, special steps must be taken to ensure the agent loads. One example is when you are starting an MPI program using a launcher that does not propagate environment variables. (If you start your MPI program in MemoryScape using the Add Parallel Program page, MemoryScape propagates the information for you.) Another is when you want to start your program outside, or independently of, TotalView, and want to attach to the program later after it has started.
There are two ways you can arrange for the heap agent to be loaded:
Link the application with the agent, as described in this section.Request that the heap agent be preloaded by setting the runtime loader's preloading environment variable. See Using env to Insert the Agent.Here is some important platform-specific information:
On AIX, the malloc replacement code and heap agent application must be in directories searched by the dynamic loader. If they are not in any of the standard directories (you can check with your system administrator), you can set LIBPATH to search these directories when you run the program. Another option is to add the directories to the program's list of search directories when you link the program. To do this, use the -L option as described in the table below. If you are in doubt about the directories being searched, you can obtain a list of the searched directories with dump -Hv <program-name>.For additional requirements with AIX, see Installing tvheap_mr.a on AIX.
On Cray, TotalView supports both static and dynamic linking. See the table below for the link lines you need to use.On Apple Mac OSXmacOS, you cannot link the agent into your program.The following table lists additional command-line linker options that you must use when you link your program:
Platform | Compiler | Binary Interface | Additional linker options |
|---|---|---|---|
Cray XT, XE, XK CLE (dynamic) | - | 64 | -L<path> -ltvheap_cnl -Wl,-rpath,<path> |
Cray XT, XE, XK CLE (static) | - | 64 | -L<path> -ltvheap_cnl |
IBM RS/6000 (all) | IBM/GCC | 32/64 | -L<path_mr> -L<path> |
AIX 5 | IBM/GCC | 32 | -L<path_mr> -L<path> <path>/aix_malloctype.o |
64 | -L<path_mr> -L<path> <path>/aix_malloctype64_5.o | ||
Linux x86-64 | GCC/Intel/PGI | 32 | -L<path> -ltvheap -Wl,-rpath,<path> |
64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> | ||
Linux PowerLE | GCC | 64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> |
Linux ARM64 | GCC | 64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> |
Sun | Sun/Apogee | 32 | -L<path> -ltvheap -R <path> |
Sun | 64 | -L<path> -ltvheap_64 -R <path> | |
GCC | 32 | -L<path> -ltvheap -Wl,-R,<path> | |
64 | -L<path> -ltvheap_64 -Wl,-R,<path> |
The following list describes the options in this table:
<path>
The absolute path to the agent in the MemoryScape installation hierarchy. More precisely, this directory is:
<installdir>/toolworks/memoryscape.<version>/<platform>/lib
<installdir>
The installation base directory name.
<version>
The MemoryScape version number.
<platform>
The platform tag.
<path_mr>
The absolute path of the malloc replacement library. This value is determined by the person who installs the MemoryScape malloc replacement library.
NOTE: The heap agent library path can be hard to determine. If you have access to the command line interface (CLI), you can use the following command to print out its path:
puts $TV::hia_local_dir
puts $TV::hia_local_dir
Other related topics are:
