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 -lmcheck 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       mstatus,  that  indicates  what type of inconsistency was detected.  If
45       abortfunc is NULL, a default function prints an error message on stderr
46       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

ATTRIBUTES

80       For   an   explanation   of   the  terms  used  in