mirror of https://github.com/mkerrisk/man-pages
172 lines
4.7 KiB
Groff
172 lines
4.7 KiB
Groff
.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH MTRACE 3 2012-04-18 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
mtrace, muntrace \- malloc tracing
|
|
.SH SYNOPSIS
|
|
.B "#include <mcheck.h>"
|
|
.sp
|
|
.B "void mtrace(void);"
|
|
.sp
|
|
.B "void muntrace(void);"
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR mtrace ()
|
|
function installs hook functions for the memory-allocation functions
|
|
.RB ( malloc (3),
|
|
.BR realloc (3)
|
|
.BR memalign (3),
|
|
.BR free (3)).
|
|
These hook functions record tracing information about memory allocation
|
|
and deallocation.
|
|
The tracing information can be used to discover memory leaks and
|
|
attempts to free nonallocated memory in a program.
|
|
|
|
The
|
|
.BR muntrace ()
|
|
function disables the hook functions installed by
|
|
.BR mtrace (),
|
|
so that tracing information is no longer recorded
|
|
for the memory-allocation functions.
|
|
If no hook functions were successfully installed by
|
|
.BR mtrace (),
|
|
.BR muntrace ()
|
|
does nothing.
|
|
|
|
When
|
|
.BR mtrace ()
|
|
is called, it checks the value of the environment variable
|
|
.BR 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
|
|
.BR MALLOC_TRACE
|
|
is not set,
|
|
or the pathname it specifies is invalid or not writable,
|
|
then no hook functions are installed, and
|
|
.BR mtrace ()
|
|
has no effect.
|
|
In set-user-ID and set-group-ID programs,
|
|
.BR MALLOC_TRACE
|
|
is ignored, and
|
|
.BR mtrace ()
|
|
has no effect.
|
|
.SH CONFORMING TO
|
|
These functions are GNU extensions.
|
|
.SH NOTES
|
|
In normal usage,
|
|
.BR mtrace ()
|
|
is called once at the start of execution of a program, and
|
|
.BR muntrace ()
|
|
is never called.
|
|
|
|
The tracing output produced after a call to
|
|
.BR mtrace ()
|
|
is textual, but not designed to be human readable.
|
|
The GNU C library provides a Perl script,
|
|
.BR mtrace (1),
|
|
that interprets the trace log and produces human-readable output.
|
|
For best results,
|
|
the traced program should be compiled with debugging enabled,
|
|
so that line-number information is recorded in the executable.
|
|
|
|
The tracing performed by
|
|
.BR mtrace ()
|
|
incurs a performance penalty (if
|
|
.B MALLOC_TRACE
|
|
points to a valid, writable pathname).
|
|
.SH BUGS
|
|
The line-number information produced by
|
|
.BR mtrace (1)
|
|
is not always precise:
|
|
the line number references may refer to the previous or following (nonblank)
|
|
line of the source code.
|
|
.SH EXAMPLE
|
|
The shell session below demonstrates the use of the
|
|
.BR mtrace ()
|
|
function and the
|
|
.BR mtrace (1)
|
|
command in a program that has memory leaks at two different locations.
|
|
The demonstration uses the following program:
|
|
.in +4
|
|
.nf
|
|
|
|
.RB "$ " "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);
|
|
}
|
|
|
|
.fi
|
|
.in
|
|
When we run the program as follows, we see that
|
|
.BR mtrace ()
|
|
diagnosed memory leaks at two different locations in the program:
|
|
.in +4n
|
|
.nf
|
|
|
|
.RB "$ " "cc \-g t_mtrace.c \-o t_mtrace"
|
|
.RB "$ " "export MALLOC_TRACE=/tmp/t"
|
|
.RB "$ " "./t_mtrace"
|
|
.RB "$ " "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
|
|
.fi
|
|
.in
|
|
|
|
The first two messages about unfreed memory correspond to the two
|
|
.BR malloc (3)
|
|
calls inside the
|
|
.I for
|
|
loop.
|
|
The final message corresponds to the call to
|
|
.BR calloc (3)
|
|
(which in turn calls
|
|
.BR malloc (3)).
|
|
.SH SEE ALSO
|
|
.BR mtrace (1),
|
|
.BR malloc (3),
|
|
.BR malloc_hook (3),
|
|
.BR mcheck (3)
|