| .\" 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 2021-03-22 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| mtrace, muntrace \- malloc tracing |
| .SH SYNOPSIS |
| .nf |
| .B "#include <mcheck.h>" |
| .PP |
| .B "void mtrace(void);" |
| .B "void muntrace(void);" |
| .fi |
| .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. |
| .PP |
| 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. |
| .PP |
| 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. |
| .PP |
| 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 ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .ad l |
| .nh |
| .TS |
| allbox; |
| lbx lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR mtrace (), |
| .BR muntrace () |
| T} Thread safety MT-Unsafe |
| .TE |
| .hy |
| .ad |
| .sp 1 |
| .\" FIXME: The marking is different from that in the glibc manual, |
| .\" markings in glibc manual are more detailed: |
| .\" |
| .\" mtrace: MT-Unsafe env race:mtrace const:malloc_hooks init |
| .\" muntrace: MT-Unsafe race:mtrace const:malloc_hooks locale |
| .\" |
| .\" But there is something wrong in glibc manual, for example: |
| .\" glibc manual says muntrace should have marking locale because it calls |
| .\" fprintf(), but muntrace does not execute area which cause locale problem. |
| .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. |
| .PP |
| 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. |
| .PP |
| 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 EXAMPLES |
| 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: |
| .PP |
| .in +4n |
| .EX |
| .RB "$ " "cat t_mtrace.c" |
| #include <mcheck.h> |
| #include <stdlib.h> |
| #include <stdio.h> |
| |
| int |
| main(int argc, char *argv[]) |
| { |
| mtrace(); |
| |
| for (int j = 0; j < 2; j++) |
| malloc(100); /* Never freed\-\-a memory leak */ |
| |
| calloc(16, 16); /* Never freed\-\-a memory leak */ |
| exit(EXIT_SUCCESS); |
| } |
| .EE |
| .in |
| .PP |
| When we run the program as follows, we see that |
| .BR mtrace () |
| diagnosed memory leaks at two different locations in the program: |
| .PP |
| .in +4n |
| .EX |
| .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 |
| .EE |
| .in |
| .PP |
| 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) |