original/man3/mtrace.3

   1 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .TH MTRACE 3 2012-04-18 "GNU" "Linux Programmer's Manual"
  24 .SH NAME
  25 mtrace, muntrace \- malloc tracing
  26 .SH SYNOPSIS
  27 .B "#include <mcheck.h>"
  28 .sp
  29 .B "void mtrace(void);"
  30 .sp
  31 .B "void muntrace(void);"
  32 .SH DESCRIPTION
  33 The
  34 .BR mtrace ()
  35 function installs hook functions for the memory-allocation functions
  36 .RB ( malloc (3),
  37 .BR realloc (3)
  38 .BR memalign (3),
  39 .BR free (3)).
  40 These hook functions record tracing information about memory allocation
  41 and deallocation.
  42 The tracing information can be used to discover memory leaks and
  43 attempts to free nonallocated memory in a program.
  44
  45 The
  46 .BR muntrace ()
  47 function disables the hook functions installed by
  48 .BR mtrace (),
  49 so that tracing information is no longer recorded
  50 for the memory-allocation functions.
  51 If no hook functions were successfully installed by
  52 .BR mtrace (),
  53 .BR muntrace ()
  54 does nothing.
  55
  56 When
  57 .BR mtrace (3)
  58 is called, it checks the value of the environment variable
  59 .BR MALLOC_TRACE ,
  60 which should contain the pathname of a file in which
  61 the tracing information is to be recorded.
  62 If the pathname is successfully opened, it is truncated to zero length.
  63
  64 If
  65 .BR MALLOC_TRACE
  66 is not set,
  67 or the pathname it specifies is invalid or not writable,
  68 then no hook functions are installed, and
  69 .BR mtrace ()
  70 has no effect.
  71 In set-user-ID and set-group-ID programs,
  72 .BR MALLOC_TRACE
  73 is ignored, and
  74 .BR mtrace ()
  75 has no effect.
  76 .SH "CONFORMING TO"
  77 These functions are GNU extensions.
  78 .SH NOTES
  79 In normal usage,
  80 .BR mtrace ()
  81 is called once at the start of execution of a program, and
  82 .BR muntrace ()
  83 is never called.
  84
  85 The tracing output produced after a call to
  86 .BR mtrace ()
  87 is textual, but not designed to be human readable.
  88 The GNU C library provides a Perl script,
  89 .BR mtrace (1),
  90 that interprets the trace log and produces human-readable output.
  91 For best results,
  92 the traced program should be compiled with debugging enabled,
  93 so that line-number information is recorded in the executable.
  94
  95 The tracing performed by
  96 .BR mtrace ()
  97 incurs a performance penalty (if
  98 .B MALLOC_TRACE
  99 points to a valid, writable pathname).
 100 .SH BUGS
 101 The line-number information produced by
 102 .BR mtrace (1)
 103 is not always precise:
 104 the line number references may refer to the previous or following (non-blank)
 105 line of the source code.
 106 .SH EXAMPLE
 107 The shell session below demonstrates the use of the
 108 .BR mtrace ()
 109 function and the
 110 .BR mtrace (1)
 111 command in a program that has memory leaks at two different locations.
 112 The demonstration uses the following program:
 113 .in +4
 114 .nf
 115
 116 .RB "$ " "cat t_mtrace.c"
 117 #include <mcheck.h>
 118 #include <stdlib.h>
 119 #include <stdio.h>
 120
 121 int
 122 main(int argc, char *argv[])
 123 {
 124     int j;
 125
 126     mtrace();
 127
 128     for (j = 0; j < 2; j++)
 129         malloc(100);            /* Never freed\-\-a memory leak */
 130
 131     calloc(16, 16);             /* Never freed\-\-a memory leak */
 132     exit(EXIT_SUCCESS);
 133 }
 134
 135 .fi
 136 .in
 137 When we run the program as follows, we see that
 138 .BR mtrace ()
 139 diagnosed memory leaks at two different locations in the program:
 140 .in +4n
 141 .nf
 142
 143 .RB "$ " "cc \-g t_mtrace.c \-o t_mtrace"
 144 .RB "$ " "export MALLOC_TRACE=/tmp/t"
 145 .RB "$ " "./t_mtrace"
 146 .RB "$ " "mtrace ./t_mtrace $MALLOC_TRACE"
 147 Memory not freed:
 148 -----------------
 149    Address     Size     Caller
 150 0x084c9378     0x64  at /home/cecilia/t_mtrace.c:12
 151 0x084c93e0     0x64  at /home/cecilia/t_mtrace.c:12
 152 0x084c9448    0x100  at /home/cecilia/t_mtrace.c:16
 153 .fi
 154 .in
 155
 156 The first two messages about unfreed memory correspond to the two
 157 .BR malloc (3)
 158 calls inside the
 159 .I for
 160 loop.
 161 The final message corresponds to the call to
 162 .BR calloc (3)
 163 (which in turn calls
 164 .BR malloc (3)).
 165 .SH "SEE ALSO"
 166 .BR mtrace (1),
 167 .BR malloc (3),
 168 .BR malloc_hook (3),
 169 .BR mcheck (3)