Debian Codegraph @

upstream/debian-unstable/man3/mtrace.3

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