1MCHECK(3)                  Linux Programmer's Manual                 MCHECK(3)
2
3
4

NAME

6       mcheck,  mcheck_check_all,  mcheck_pedantic,  mprobe - heap consistency
7       checking
8

SYNOPSIS

10       #include <mcheck.h>
11
12       int mcheck(void (*abortfunc)(enum mcheck_status mstatus));
13
14       int mcheck_pedantic(void (*abortfunc)(enum mcheck_status mstatus));
15
16       void mcheck_check_all(void);
17
18       enum mcheck_status mprobe(void *ptr);
19

DESCRIPTION

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
28       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
34       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
38       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
42       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
48       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
52       The  following list describes the values returned by mprobe() or passed
53       as the mstatus argument when abortfunc is invoked:
54
55       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
59       MCHECK_OK (mprobe() only)
60              No inconsistency detected.
61
62       MCHECK_HEAD
63              Memory preceding an allocated block was clobbered.
64
65       MCHECK_TAIL
66              Memory following an allocated block was clobbered.
67
68       MCHECK_FREE
69              A block of memory was freed twice.
70

RETURN VALUE

72       mcheck() and mcheck_pedantic() return 0 on success, or -1 on error.
73

VERSIONS

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

CONFORMING TO

80       These functions are GNU extensions.
81

NOTES

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

EXAMPLE

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
93           $ ./a.out
94           About to free
95
96           About to free a second time
97           block freed twice
98           Aborted (core dumped)
99
100   Program source
101
102       #include <stdlib.h>
103       #include <stdio.h>
104       #include <mcheck.h>
105
106       int
107       main(int argc, char *argv[])
108       {
109           char *p;
110
111           if (mcheck(NULL) != 0) {
112               fprintf(stderr, "mcheck() failed\n");
113
114               exit(EXIT_FAILURE);
115           }
116
117           p = malloc(1000);
118
119           fprintf(stderr, "About to free\n");
120           free(p);
121           fprintf(stderr, "\nAbout to free a second time\n");
122           free(p);
123
124           exit(EXIT_SUCCESS);
125       }
126

SEE ALSO

128       malloc(3), mallopt(3), mtrace(3)
129

COLOPHON

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/.
134
135
136
137GNU                               2012-04-18                         MCHECK(3)
Impressum