X-Git-Url: http://git.osdn.net/view?p=linuxjm%2FLDP_man-pages.git;a=blobdiff_plain;f=original%2Fman3%2Fmtrace.3;h=3ce6250681b1ab37baec622a13096974dbce513c;hp=dc84732ad1c14148931802f20381c0eb5f8e5e5e;hb=781fb70b02c5d368a8ccd67d3c074c7aa8eb0c1a;hpb=657aaa2623246005bf75eb3c64da9382236c130a diff --git a/original/man3/mtrace.3 b/original/man3/mtrace.3 index dc84732a..3ce62506 100644 --- a/original/man3/mtrace.3 +++ b/original/man3/mtrace.3 @@ -1,9 +1,28 @@ -.\" Copyright 2002 Walter Harms (walter.harms@informatik.uni-oldenburg.de) -.\" Distributed under GPL -.\" the glibc-info pages are very helpful here -.TH MTRACE 3 2002-07-20 "GNU" "Linux Programmer's Manual" +.\" Copyright (c) 2012 by Michael Kerrisk +.\" +.\" 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. +.\" +.TH MTRACE 3 2012-03-22 "GNU" "Linux Programmer's Manual" .SH NAME -mtrace, muntrace \- malloc debugging +mtrace, muntrace \- malloc tracing .SH SYNOPSIS .B "#include " .sp @@ -11,33 +30,139 @@ mtrace, muntrace \- malloc debugging .sp .B "void muntrace(void);" .SH DESCRIPTION -The function +The .BR mtrace () -installs handlers for -.BR malloc (3), +function installs hook functions for the memory-allocation functions +.RB ( malloc (3), .BR realloc (3) -and -.BR free (3). -The function +.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 () -disables these handlers. -.br -The environment variable -.B MALLOC_TRACE -defines a file where +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 (3) +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 () -writes its output. -This file must be writable to the user or +has no effect. +In set-user-ID and set-group-ID programs, +.BR MALLOC_TRACE +is ignored, and .BR mtrace () -will do nothing. -If the file is not empty it will be truncated. +has no effect. .SH "CONFORMING TO" -These are GNU extensions. +These functions are GNU extensions. .SH NOTES -The output of +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 (non-blank) +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 +#include +#include + +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 () -will be ASCII but not in a friendly format. -So glibc comes with a perl-script called mtrace to make sense of it. +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)