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