MTRACE(3) Linux Programmer's Manual MTRACE(3)
NAME
mtrace, muntrace - malloc tracing
SYNOPSIS
#include <mcheck.h>
void mtrace(void);
void muntrace(void);
DESCRIPTION
The mtrace() function installs hook functions for the memory-allocation
functions (malloc(3), realloc(3) memalign(3), free(3)). These hook
functions record tracing information about memory allocation and deal-
location. The tracing information can be used to discover memory leaks
and attempts to free nonallocated memory in a program.
The muntrace() function disables the hook functions installed by
mtrace(), so that tracing information is no longer recorded for the
memory-allocation functions. If no hook functions were successfully
installed by mtrace(), muntrace() does nothing.
When mtrace() is called, it checks the value of the environment vari-
able MALLOC_TRACE, which should contain the pathname of a file in which
the tracing information is to be recorded. If the pathname is success-
fully opened, it is truncated to zero length.
If MALLOC_TRACE is not set, or the pathname it specifies is invalid or
not writable, then no hook functions are installed, and mtrace() has no
effect. In set-user-ID and set-group-ID programs, MALLOC_TRACE is
ignored, and mtrace() has no effect.
CONFORMING TO
These functions are GNU extensions.
NOTES
In normal usage, mtrace() is called once at the start of execution of a
program, and muntrace() is never called.
The tracing output produced after a call to mtrace() is textual, but
not designed to be human readable. The GNU C library provides a Perl
script, mtrace(1), that interprets the trace log and produces human-
readable output. For best results, the traced program should be com-
piled with debugging enabled, so that line-number information is
recorded in the executable.
The tracing performed by mtrace() incurs a performance penalty (if MAL-
LOC_TRACE points to a valid, writable pathname).
BUGS
The line-number information produced by mtrace(1) is not always pre-
cise: the line number references may refer to the previous or following
(non-blank) line of the source code.
EXAMPLE
The shell session below demonstrates the use of the mtrace() function
and the mtrace(1) command in a program that has memory leaks at two
different locations. The demonstration uses the following program:
$ cat t_mtrace.c
#include <mcheck.h>
#include <stdlib.h>
#include <stdio.h>
int
main(int argc, char *argv[])
{
int j;
mtrace();
for (j = 0; j < 2; j++)
malloc(100); /* Never freed--a memory leak */
calloc(16, 16); /* Never freed--a memory leak */
exit(EXIT_SUCCESS);
}
When we run the program as follows, we see that mtrace() diagnosed mem-
ory leaks at two different locations in the program:
$ cc -g t_mtrace.c -o t_mtrace
$ export MALLOC_TRACE=/tmp/t
$ ./t_mtrace
$ mtrace ./t_mtrace $MALLOC_TRACE
Memory not freed:
-----------------
Address Size Caller
0x084c9378 0x64 at /home/cecilia/t_mtrace.c:12
0x084c93e0 0x64 at /home/cecilia/t_mtrace.c:12
0x084c9448 0x100 at /home/cecilia/t_mtrace.c:16
The first two messages about unfreed memory correspond to the two mal-
loc(3) calls inside the for loop. The final message corresponds to the
call to calloc(3) (which in turn calls malloc(3)).
SEE ALSO
mtrace(1), malloc(3), malloc_hook(3), mcheck(3)
COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A
description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
GNU 2012-04-18 MTRACE(3)