]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fd298193 MK |
2 | .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fd298193 | 5 | .\" |
4c1c5274 | 6 | .TH mcheck 3 (date) "Linux man-pages (unreleased)" |
fd298193 | 7 | .SH NAME |
90d4c3de | 8 | mcheck, mcheck_check_all, mcheck_pedantic, mprobe \- heap consistency checking |
67da5adb AC |
9 | .SH LIBRARY |
10 | Standard C library | |
8fc3b2cf | 11 | .RI ( libc ", " \-lc ) |
fd298193 MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .B #include <mcheck.h> | |
c6d039a3 | 15 | .P |
fd298193 | 16 | .BI "int mcheck(void (*" abortfunc ")(enum mcheck_status " mstatus )); |
fd298193 | 17 | .BI "int mcheck_pedantic(void (*" abortfunc ")(enum mcheck_status " mstatus )); |
fd298193 | 18 | .B void mcheck_check_all(void); |
c6d039a3 | 19 | .P |
fd298193 | 20 | .BI "enum mcheck_status mprobe(void *" ptr ); |
fd298193 MK |
21 | .fi |
22 | .SH DESCRIPTION | |
23 | The | |
24 | .BR mcheck () | |
25 | function installs a set of debugging hooks for the | |
26 | .BR malloc (3) | |
27 | family of memory-allocation functions. | |
28 | These hooks cause certain consistency checks to be performed | |
29 | on the state of the heap. | |
30 | The checks can detect application errors such as freeing a block of memory | |
31 | more than once or corrupting the bookkeeping data structures | |
32 | that immediately precede a block of allocated memory. | |
c6d039a3 | 33 | .P |
fd298193 MK |
34 | To be effective, the |
35 | .BR mcheck () | |
36 | function must be called before the first call to | |
37 | .BR malloc (3) | |
38 | or a related function. | |
39 | In cases where this is difficult to ensure, linking the program with | |
1ae6b2c7 | 40 | .I \-lmcheck |
fd298193 MK |
41 | inserts an implicit call to |
42 | .BR mcheck () | |
43 | (with a NULL argument) | |
44 | before the first call to a memory-allocation function. | |
c6d039a3 | 45 | .P |
fd298193 MK |
46 | The |
47 | .BR mcheck_pedantic () | |
48 | function is similar to | |
49 | .BR mcheck (), | |
50 | but performs checks on all allocated blocks whenever | |
51 | one of the memory-allocation functions is called. | |
52 | This can be very slow! | |
c6d039a3 | 53 | .P |
fd298193 MK |
54 | The |
55 | .BR mcheck_check_all () | |
56 | function causes an immediate check on all allocated blocks. | |
33a0ccb2 | 57 | This call is effective only if |
fd298193 MK |
58 | .BR mcheck () |
59 | is called beforehand. | |
c6d039a3 | 60 | .P |
fd298193 MK |
61 | If the system detects an inconsistency in the heap, |
62 | the caller-supplied function pointed to by | |
63 | .I abortfunc | |
99bf4345 | 64 | is invoked with a single argument, |
fd298193 MK |
65 | .IR mstatus , |
66 | that indicates what type of inconsistency was detected. | |
67 | If | |
68 | .I abortfunc | |
69 | is NULL, a default function prints an error message on | |
1ae6b2c7 | 70 | .I stderr |
fd298193 MK |
71 | and calls |
72 | .BR abort (3). | |
c6d039a3 | 73 | .P |
fd298193 MK |
74 | The |
75 | .BR mprobe () | |
76 | function performs a consistency check on | |
77 | the block of allocated memory pointed to by | |
78 | .IR ptr . | |
79 | The | |
80 | .BR mcheck () | |
81 | function should be called beforehand (otherwise | |
82 | .BR mprobe () | |
83 | returns | |
84 | .BR MCHECK_DISABLED ). | |
c6d039a3 | 85 | .P |
fd298193 MK |
86 | The following list describes the values returned by |
87 | .BR mprobe () | |
88 | or passed as the | |
89 | .I mstatus | |
3960d7a2 | 90 | argument when |
fd298193 MK |
91 | .I abortfunc |
92 | is invoked: | |
93 | .TP | |
94 | .BR MCHECK_DISABLED " (" mprobe "() only)" | |
95 | .BR mcheck () | |
96 | was not called before the first memory allocation function was called. | |
97 | Consistency checking is not possible. | |
98 | .TP | |
99 | .BR MCHECK_OK " (" mprobe "() only)" | |
100 | No inconsistency detected. | |
101 | .TP | |
102 | .B MCHECK_HEAD | |
103 | Memory preceding an allocated block was clobbered. | |
104 | .TP | |
105 | .B MCHECK_TAIL | |
106 | Memory following an allocated block was clobbered. | |
107 | .TP | |
108 | .B | |
109 | MCHECK_FREE | |
110 | A block of memory was freed twice. | |
111 | .SH RETURN VALUE | |
112 | .BR mcheck () | |
113 | and | |
114 | .BR mcheck_pedantic () | |
115 | return 0 on success, or \-1 on error. | |
834fde73 ZL |
116 | .SH ATTRIBUTES |
117 | For an explanation of the terms used in this section, see | |
118 | .BR attributes (7). | |
119 | .TS | |
120 | allbox; | |
c466875e | 121 | lbx lb lb |
834fde73 ZL |
122 | l l l. |
123 | Interface Attribute Value | |
124 | T{ | |
9e54434e BR |
125 | .na |
126 | .nh | |
834fde73 ZL |
127 | .BR mcheck (), |
128 | .BR mcheck_pedantic (), | |
834fde73 ZL |
129 | .BR mcheck_check_all (), |
130 | .BR mprobe () | |
131 | T} Thread safety T{ | |
9e54434e BR |
132 | .na |
133 | .nh | |
834fde73 | 134 | MT-Unsafe race:mcheck |
834fde73 ZL |
135 | const:malloc_hooks |
136 | T} | |
137 | .TE | |
4131356c AC |
138 | .SH STANDARDS |
139 | GNU. | |
140 | .SH HISTORY | |
141 | .TP | |
196224f7 | 142 | .BR mcheck_pedantic () |
4131356c | 143 | .TQ |
196224f7 | 144 | .BR mcheck_check_all () |
4131356c AC |
145 | glibc 2.2. |
146 | .TP | |
196224f7 | 147 | .BR mcheck () |
4131356c | 148 | .TQ |
196224f7 | 149 | .BR mprobe () |
4131356c | 150 | glibc 2.0. |
fd298193 MK |
151 | .SH NOTES |
152 | Linking a program with | |
153 | .I \-lmcheck | |
154 | and using the | |
155 | .B MALLOC_CHECK_ | |
156 | environment variable (described in | |
157 | .BR mallopt (3)) | |
158 | cause the same kinds of errors to be detected. | |
159 | But, using | |
160 | .B MALLOC_CHECK_ | |
161 | does not require the application to be relinked. | |
162 | .\" But is MALLOC_CHECK_ slower? | |
a14af333 | 163 | .SH EXAMPLES |
fd298193 MK |
164 | The program below calls |
165 | .BR mcheck () | |
166 | with a NULL argument and then frees the same block of memory twice. | |
167 | The following shell session demonstrates what happens | |
168 | when running the program: | |
c6d039a3 | 169 | .P |
fd298193 | 170 | .in +4n |
e646a1ba | 171 | .EX |
fd298193 MK |
172 | .RB "$" " ./a.out" |
173 | About to free | |
fe5dba13 | 174 | \& |
fd298193 MK |
175 | About to free a second time |
176 | block freed twice | |
177 | Aborted (core dumped) | |
b8302363 | 178 | .EE |
fd298193 MK |
179 | .in |
180 | .SS Program source | |
181 | \& | |
df2441df | 182 | .\" [[memory leak]] SRC BEGIN (mcheck.c) |
e7d0bb47 | 183 | .EX |
fd298193 | 184 | #include <mcheck.h> |
ad3868f0 AC |
185 | #include <stdio.h> |
186 | #include <stdlib.h> | |
fe5dba13 | 187 | \& |
fd298193 | 188 | int |
f1e39c1e | 189 | main(void) |
fd298193 MK |
190 | { |
191 | char *p; | |
fe5dba13 | 192 | \& |
fd298193 | 193 | if (mcheck(NULL) != 0) { |
d1a71985 | 194 | fprintf(stderr, "mcheck() failed\en"); |
fe5dba13 | 195 | \& |
fd298193 MK |
196 | exit(EXIT_FAILURE); |
197 | } | |
fe5dba13 | 198 | \& |
fd298193 | 199 | p = malloc(1000); |
fe5dba13 | 200 | \& |
d1a71985 | 201 | fprintf(stderr, "About to free\en"); |
fd298193 | 202 | free(p); |
d1a71985 | 203 | fprintf(stderr, "\enAbout to free a second time\en"); |
fd298193 | 204 | free(p); |
fe5dba13 | 205 | \& |
fd298193 MK |
206 | exit(EXIT_SUCCESS); |
207 | } | |
e7d0bb47 | 208 | .EE |
b0b6ab4e | 209 | .\" SRC END |
fd298193 MK |
210 | .SH SEE ALSO |
211 | .BR malloc (3), | |
fd298193 MK |
212 | .BR mallopt (3), |
213 | .BR mtrace (3) |