man3/mtrace.3

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