Mtrace

mtrace is the memory debugger included in the GNU C Library.

Use

The function mtrace installs handlers for malloc, realloc and free; the function muntrace disables these handlers. Their prototypes, defined in the header file mcheck.h, are

void mtrace(void);

void muntrace(void);

The handlers log all memory allocations and frees to a file defined by the environment variable MALLOC_TRACE (if the variable is unset, describes an invalid filename, or describes a filename the user does not have permissions to, the handlers are not installed).

A perl script called mtrace, not to be confused with the function of the same name, is also distributed with the GNU C Library; the script parses through the output file and reports all allocations that were not freed.

Usage example

Bad Source Code

The following is an example of bad source code. The problem with the program is that it allocates memory, but doesn’t free the memory before exiting.

#include

int main() {

int * a;

a = malloc(sizeof(int)); /* allocate memory and assign it to the pointer */ return 0; /* we exited the program without freeing memory */

/* we should have released the allocated memory with the command “free(a)” */

}

MTrace Usage

1. The environment variable “MALLOC_TRACE” must be set to the path of the output file. Setting environment variables is slightly different on every shell type. In the BASH shell on Linux, the command is as follows:

MALLOC_TRACE=/home/YourUserName/path/to/program/MallocTraceOutputFile.txtexport MALLOC_TRACE;

2. The required library (“mcheck.h”) must be included in the source code. This is done by adding the following line to the top of the .c or .cpp file, as shown below:

#include

3. The function “mtrace()” must be called before you start allocating memory. It is usually easiest to call mtrace() at the very beginning of the main function.

mtrace();

4. The program should be compiled and run. Note that you need to use the -g option to enable profiling. In GCC on Linux, this can be done using the following commands:

gcc yourProgram.c -g./a.out

5. The memory leak information will be reported in the file specified by the MALLOC_TRACE environment variable. The difficulty is, this file will be in a computer-readable format. Most Linux machines come with a console command called “mtrace”, that converts the computer file into human-readable text as shown below. If you do not have access to this console command, there is a perl script that can be downloaded and will accomplish the same task. mtrace follows the following syntax:

mtrace

For example:

mtrace a.out MallocTraceOutputFile.txt

MTrace Output

If the mtrace command reports “No Memory Leaks”, then all memory that was allocated in the last execution of that program was also released, which is the way it should be. If, on the other hand, mtrace gives output such as that below, it means the programmer still has some work to do.

Memory not freed:----------------- Address Size Caller0x08049910 0x4 at /home/sureshsathiah/tips/leak.c:9

Good Source Code

The following is an example of great source code. It releases memory after it is allocated, and it uses mtrace to notify the programmer if there are memory leaks.

#include
#include

int main() {

mtrace(); /* Starts the recording of memory allocations and releases */

int* a = NULL;

a = malloc(sizeof(int)); /* allocate memory and assign it to the pointer */ if (a = NULL) { return 1; /* error */ }

free(a); /* we free the memory we allocated so we don't have leaks */ muntrace(); return 0; /* exit */

}

See also

* malloc

External links

* [http://www.gnu.org/software/libc/manual/html_node/Allocation-Debugging.html GNU C Library manual: Allocation debugging]
* [http://www.sourcentral.org/man/ubuntu610/3+mtrace Manual page for mtrace]
* [http://www.sourcentral.org/man/ubuntu610/1+mtrace Manual page for the perl script mtrace]
* [http://www.linuxjournal.com/article/6059 Linux Journal: Memory Leak Detection in Embedded Systems]