Linking Your Application with the Agent
TotalView 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 TotalView agent does not replace standard memory functions; it just monitors what they do. For more information, see “Behind the Scenes” on page 10.
In most cases, TotalView 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 TotalView using the Add Parallel Program page, TotalView 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 page 15.
On Cray, TotalView supports both static and dynamic linking. See the table below for the link lines you need to use.On Apple Mac OSX, you cannot link the agent into your program.Table 15 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 | -dynamic -L<path> -ltvheap_64 -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 1 | GCC/Intel/PGI | 32 | -L<path> -ltvheap -Wl,-rpath,<path> |
Linux x86-64 1 | GCC/Intel/PGI | 32 | -L<path> -ltvheap -Wl,-rpath,<path> |
64 | -L<path> -ltvheap_64 -Wl,-rpath,<path> | ||
Linux Power | 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> |
1 On Ubuntu platforms, if the link line fails to start TotalView, try adding the additional flag -Wl,-no-as-needed. This flag should occur before the linking of tvheap, so on 64-bit platforms the link line would be:
-L<path> -Wl,-no-as-needed -ltvheap_64 -Wl,-rpath,<path>
-L<path> -Wl,-no-as-needed -ltvheap_64 -Wl,-rpath,<path>
Table Options:
<path>The absolute path to the agent in the TotalView installation hierarchy, located at:
<installdir>/toolworks/TotalView.<version>/<platform>/lib
<installdir>The installation base directory name
<version>TotalView 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 TotalView malloc replacement library.
