This tool is to be used to aid the discovery of memory leaks in single and multi threaded C/C++ applications on OS/390.
The tool is distributed "as is". The tool has been compiled under OS/390 C/C++ Compiler Ver 2 Rel 4, LE Ver 1 Rel 8 and tested under OS/390 Ver 2 Rel 5. No official guarantees are made for other versions/releases of OS/390, however upward compatibility of the above software packages should maintain the usability of the tool.
The tool is it's own DLL (or shared object if you will). The DLL defines it's own implementation for memory management in terms of:
delete operator, and
delete operator. When you link this DLL into your code, the run-time environment will utilize the tools' implementation for allocating and deallocating memory, instead of the traditional implementation.
The memory management implementation is as follows: the tool "logs" when an allocate is made, then allocates the actual storage and returns the memory to the caller. When a deallocate is made, the tool matches the deallocate with it's corresponding allocate (this is done by saving the address location of the memory that was allocated) and removes the "log" information about this allocation. The tool will only report unmatched allocations (those that weren't freed, thus possible leaks). The tool is even smarter by also "logging" multiple deallocates. If memory is freed multiple times, the tool reports all the deallocates after the first one as unmatched deallocates. One note of interest with regard to unmatched deallocates is the address of the memory that is freed. The report gives the address of the storage that was deallocated an extra time. If this address is NOT 0 (zero), then be weary. The multiple free is actually trying to free a real address. Hopefully this address should be 0 (zero), thus not really a problem, just bad coding practice.
If the module(s) you are linking the tool with have been compiled with the c89 compiler OR the cxx compiler without the -+ option, then you need to recompile them with the -W0,DLL option. This is necessary because standard C is not familiar with DLL linkage. This option tells the module to expect to be linked with a DLL.
For C++, the tool requires the usage of the prelinker. If the prelinker is not invoked, the tool will NOT report memory allocations and deallocations for C++. To force the invocation of the prelinker, export the environment variable _ < xxx > _STEPS=-1, where < xxx > is the name of the linker you are using. For example, if you use cxx to link your program, export _CXX_STEPS=-1 before trying to link the tool with your program.
After those requirements are met, all you need to do is link the tool DLL with your code. This can be done by linking in the export file ( memcheck.x) with your code.
The tool keeps track of the "logging" of allocates and deallocates internally. To force the results out to a report file, there is a function call to be made. The prototype is as follows:
int MemPrintActive(MemPrintActiveFreeAction freeAction, MemPrintActivePrintAction printAction, char *title, char *inputFileName)
- freeAction - allows you to tell the tool to free all allocated memory up to that point, or not to free allocated memory.
- printAction - allows you to tell the tool to actually print a report, on not to bother. The reason you would call this function, but not want to generate the report is because this function also allows you to free all allocated storage (see the freeAction parameter).
- title - a string that it outputted at the beginning of the report.
- inputFileName - the full path of the file name to output the report in.
The values for freeAction and printAction are enumerated constants defined in memcheck.h. You will need to include this file in the module where you intend to use the
Here is an example call to generate the report:
MemPrintActive(MEM_DO_NOT_FREE_RESOURCES, MEM_PRINT_REPORT, "My Title, "/tmp/report.mem");
NOTE: The outputting of the report to a file actually appends the report to the end of the file. If you call this function with the same inputFileName parameter multiple times, the report will be appended to the end each time. Each report it separated by the title parameter, and is also time stamped. Make sure you are looking at the right report when doing memory leak analysis!
The tool makes use of shell environment variables to indicate the level of reporting you wish to see. There are three environment variables that you will need to export in your shell environment. They are:
- _EUV_MEMCHECK - allows you to turn MemCheck Analysis on or off. To turn it on, export the variable equal to 1. To turn analysis off, remove the variable completely from your environment.
- _EUV_MEMCHECK_DEPTH - depth of callers to monitor on mismatched storage requests. This must be an integer value.
- _EUV_MEMTRACE - allows you to turn MemCheck Tracing on or off. Tracing allows you to monitor all allocations and deallocations regarless if they are leaks or not. To turn it on, export the variable equal to 1. To turn tracing off, remove the variable completely from your environment. Tracing messages go to standard out. Note: To use this feature, MemCheck Analysis must be enabled. (see _EUV_MEMCHECK)
- _EUV_MEMTRACE_DEPTH - depth of callers to trace on storage requests. This must be an integer value which is less than or equal to the _EUV_MEMCHECK_DEPTH value.
- _EUV_MEMCHECK_OVERLAY - performs checking of overlays off the end of malloced storage (checked at free time).
- _EUV_MEMCHECK_UNDERLAY - performs checking of overlays off the beginning of malloced storage (checked at free time).