1MCHECK(3) Linux Programmer's Manual MCHECK(3)
2
6 mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap consistency
7 checking
8
10 #include <mcheck.h>
11 int mcheck(void (*abortfunc)(enum mcheck_status mstatus));
13 int mcheck_pedantic(void (*abortfunc)(enum mcheck_status mstatus));
15 void mcheck_check_all(void);
17 enum mcheck_status mprobe(void *ptr);
19
21 The mcheck() function installs a set of debugging hooks for the mal‐
22 loc(3) family of memory-allocation functions. These hooks cause cer‐
23 tain consistency checks to be performed on the state of the heap. The
24 checks can detect application errors such as freeing a block of memory
25 more than once or corrupting the bookkeeping data structures that imme‐
26 diately precede a block of allocated memory.
27 To be effective, the mcheck() function must be called before the first
29 call to malloc(3) or a related function. In cases where this is diffi‐
30 cult to ensure, linking the program with -mcheck inserts an implicit
31 call to mcheck() (with a NULL argument) before the first call to a mem‐
32 ory-allocation function.
33 The mcheck_pedantic() function is similar to mcheck(), but performs
35 checks on all allocated blocks whenever one of the memory-allocation
36 functions is called. This can be very slow!
37 The mcheck_check_all() function causes an immediate check on all allo‐
39 cated blocks. This call is effective only if mcheck() is called
40 beforehand.
41 If the system detects an inconsistency in the heap, the caller-supplied
43 function pointed to by abortfunc is invoked with a single argument
44 argument, mstatus, that indicates what type of inconsistency was
45 detected. If abortfunc is NULL, a default function prints an error
46 message on stderr and calls abort(3).
47 The mprobe() function performs a consistency check on the block of
49 allocated memory pointed to by ptr. The mcheck() function should be
50 called beforehand (otherwise mprobe() returns MCHECK_DISABLED).
51 The following list describes the values returned by mprobe() or passed
53 as the mstatus argument when abortfunc is invoked:
54 MCHECK_DISABLED (mprobe() only)
56 mcheck() was not called before the first memory allocation func‐
57 tion was called. Consistency checking is not possible.
58 MCHECK_OK (mprobe() only)
60 No inconsistency detected.
61 MCHECK_HEAD
63 Memory preceding an allocated block was clobbered.
64 MCHECK_TAIL
66 Memory following an allocated block was clobbered.
67 MCHECK_FREE
69 A block of memory was freed twice.
70
72 mcheck() and mcheck_pedantic() return 0 on success, or -1 on error.
73
75 The mcheck_pedantic() and mcheck_check_all() functions are available
76 since glibc 2.2. The mcheck() and mprobe() functions are present since
77 at least glibc 2.0
78
80 These functions are GNU extensions.
81
83 Linking a program with -lmcheck and using the MALLOC_CHECK_ environment
84 variable (described in mallopt(3)) cause the same kinds of errors to be
85 detected. But, using MALLOC_CHECK_ does not require the application to
86 be relinked.
87
89 The program below calls mcheck() with a NULL argument and then frees
90 the same block of memory twice. The following shell session demon‐
91 strates what happens when running the program:
92 $ ./a.out
94 About to free
95 About to free a second time
97 block freed twice
98 Aborted (core dumped)
99 Program source
101 #include <stdlib.h>
103 #include <stdio.h>
104 #include <mcheck.h>
105 int
107 main(int argc, char *argv[])
108 {
109 char *p;
110 if (mcheck(NULL) != 0) {
112 fprintf(stderr, "mcheck() failed\n");
113 exit(EXIT_FAILURE);
115 }
116 p = malloc(1000);
118 fprintf(stderr, "About to free\n");
120 free(p);
121 fprintf(stderr, "\nAbout to free a second time\n");
122 free(p);
123 exit(EXIT_SUCCESS);
125 }
126
128 malloc(3), mallopt(3), mtrace(3)
129
131 This page is part of release 3.53 of the Linux man-pages project. A
132 description of the project, and information about reporting bugs, can
133 be found at http://www.kernel.org/doc/man-pages/.
134GNU 2012-04-18 MCHECK(3)