mtrace(3) Library Functions Manual mtrace(3)
NAME
mtrace, muntrace - malloc tracing
LIBRARY
Standard C library (libc, -lc)
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 deallo-
cation. 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 mem-
ory-allocation functions. If no hook functions were successfully in-
stalled by mtrace(), muntrace() does nothing.
When mtrace() is called, it checks the value of the environment variable
MALLOC_TRACE, which should contain the pathname of a file in which the
tracing information is to be recorded. If the pathname is successfully
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 ig-
nored, and mtrace() has no effect.
ATTRIBUTES
For an explanation of the terms used in this section, see attributes(7).
┌──────────────────────────────────────────┬───────────────┬───────────┐
│ Interface │ Attribute │ Value │
├──────────────────────────────────────────┼───────────────┼───────────┤
│ mtrace(), muntrace() │ Thread safety │ MT-Unsafe │
└──────────────────────────────────────────┴───────────────┴───────────┘
STANDARDS
GNU.
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 precise:
the line number references may refer to the previous or following (non-
blank) line of the source code.
EXAMPLES
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 dif-
ferent locations. The demonstration uses the following program:
$ cat t_mtrace.c
#include <mcheck.h>
#include <stdio.h>
#include <stdlib.h>
int
main(void)
{
mtrace();
for (unsigned int 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)
Linux man-pages 6.9.1 2024-05-02 mtrace(3)
Generated by dwww version 1.16 on Tue Dec 16 04:26:48 CET 2025.