man3/mtrace.3

   1 '\" t
   2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH mtrace 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 mtrace, muntrace \- malloc tracing
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B "#include <mcheck.h>"
  15 .P
  16 .B "void mtrace(void);"
  17 .B "void muntrace(void);"
  18 .fi
  19 .SH DESCRIPTION
  20 The
  21 .BR mtrace ()
  22 function installs hook functions for the memory-allocation functions
  23 .RB ( malloc (3),
  24 .BR realloc (3)
  25 .BR memalign (3),
  26 .BR free (3)).
  27 These hook functions record tracing information about memory allocation
  28 and deallocation.
  29 The tracing information can be used to discover memory leaks and
  30 attempts to free nonallocated memory in a program.
  31 .P
  32 The
  33 .BR muntrace ()
  34 function disables the hook functions installed by
  35 .BR mtrace (),
  36 so that tracing information is no longer recorded
  37 for the memory-allocation functions.
  38 If no hook functions were successfully installed by
  39 .BR mtrace (),
  40 .BR muntrace ()
  41 does nothing.
  42 .P
  43 When
  44 .BR mtrace ()
  45 is called, it checks the value of the environment variable
  46 .BR MALLOC_TRACE ,
  47 which should contain the pathname of a file in which
  48 the tracing information is to be recorded.
  49 If the pathname is successfully opened, it is truncated to zero length.
  50 .P
  51 If
  52 .B MALLOC_TRACE
  53 is not set,
  54 or the pathname it specifies is invalid or not writable,
  55 then no hook functions are installed, and
  56 .BR mtrace ()
  57 has no effect.
  58 In set-user-ID and set-group-ID programs,
  59 .B MALLOC_TRACE
  60 is ignored, and
  61 .BR mtrace ()
  62 has no effect.
  63 .SH ATTRIBUTES
  64 For an explanation of the terms used in this section, see
  65 .BR attributes (7).
  66 .TS
  67 allbox;
  68 lbx lb lb
  69 l l l.
  70 Interface       Attribute       Value
  71 T{
  72 .na
  73 .nh
  74 .BR mtrace (),
  75 .BR muntrace ()
  76 T}      Thread safety   MT-Unsafe
  77 .TE
  78 .\" FIXME: The marking is different from that in the glibc manual,
  79 .\" markings in glibc manual are more detailed:
  80 .\"
  81 .\"      mtrace: MT-Unsafe env race:mtrace const:malloc_hooks init
  82 .\"      muntrace: MT-Unsafe race:mtrace const:malloc_hooks locale
  83 .\"
  84 .\" But there is something wrong in glibc manual, for example:
  85 .\" glibc manual says muntrace should have marking locale because it calls
  86 .\" fprintf(), but muntrace does not execute area which cause locale problem.
  87 .SH STANDARDS
  88 GNU.
  89 .SH NOTES
  90 In normal usage,
  91 .BR mtrace ()
  92 is called once at the start of execution of a program, and
  93 .BR muntrace ()
  94 is never called.
  95 .P
  96 The tracing output produced after a call to
  97 .BR mtrace ()
  98 is textual, but not designed to be human readable.
  99 The GNU C library provides a Perl script,
 100 .BR mtrace (1),
 101 that interprets the trace log and produces human-readable output.
 102 For best results,
 103 the traced program should be compiled with debugging enabled,
 104 so that line-number information is recorded in the executable.
 105 .P
 106 The tracing performed by
 107 .BR mtrace ()
 108 incurs a performance penalty (if
 109 .B MALLOC_TRACE
 110 points to a valid, writable pathname).
 111 .SH BUGS
 112 The line-number information produced by
 113 .BR mtrace (1)
 114 is not always precise:
 115 the line number references may refer to the previous or following (nonblank)
 116 line of the source code.
 117 .SH EXAMPLES
 118 The shell session below demonstrates the use of the
 119 .BR mtrace ()
 120 function and the
 121 .BR mtrace (1)
 122 command in a program that has memory leaks at two different locations.
 123 The demonstration uses the following program:
 124 .P
 125 .in +4n
 126 .RB "$ " "cat t_mtrace.c"
 127 .\" [[memory leak]] SRC BEGIN (t_mtrace.c)
 128 .EX
 129 #include <mcheck.h>
 130 #include <stdio.h>
 131 #include <stdlib.h>
 132 \&
 133 int
 134 main(void)
 135 {
 136     mtrace();
 137 \&
 138     for (unsigned int j = 0; j < 2; j++)
 139         malloc(100);            /* Never freed\-\-a memory leak */
 140 \&
 141     calloc(16, 16);             /* Never freed\-\-a memory leak */
 142     exit(EXIT_SUCCESS);
 143 }
 144 .EE
 145 .\" SRC END
 146 .in
 147 .P
 148 When we run the program as follows, we see that
 149 .BR mtrace ()
 150 diagnosed memory leaks at two different locations in the program:
 151 .P
 152 .in +4n
 153 .EX
 154 .RB "$ " "cc \-g t_mtrace.c \-o t_mtrace"
 155 .RB "$ " "export MALLOC_TRACE=/tmp/t"
 156 .RB "$ " "./t_mtrace"
 157 .RB "$ " "mtrace ./t_mtrace $MALLOC_TRACE"
 158 Memory not freed:
 159 -\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 160    Address     Size     Caller
 161 0x084c9378     0x64  at /home/cecilia/t_mtrace.c:12
 162 0x084c93e0     0x64  at /home/cecilia/t_mtrace.c:12
 163 0x084c9448    0x100  at /home/cecilia/t_mtrace.c:16
 164 .EE
 165 .in
 166 .P
 167 The first two messages about unfreed memory correspond to the two
 168 .BR malloc (3)
 169 calls inside the
 170 .I for
 171 loop.
 172 The final message corresponds to the call to
 173 .BR calloc (3)
 174 (which in turn calls
 175 .BR malloc (3)).
 176 .SH SEE ALSO
 177 .BR mtrace (1),
 178 .BR malloc (3),
 179 .BR malloc_hook (3),
 180 .BR mcheck (3)