mprobe(3)

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  this  section,  see
81       attributes(7).
82
83       ┌─────────────────────────────┬───────────────┬───────────────────────┐
84       │Interface                    │ Attribute     │ Value                 │
85       ├─────────────────────────────┼───────────────┼───────────────────────┤
86       │mcheck(), mcheck_pedantic(), │ Thread safety │ MT-Unsafe race:mcheck │
87       │mcheck_check_all(), mprobe() │               │ const:malloc_hooks    │
88       └─────────────────────────────┴───────────────┴───────────────────────┘
89

CONFORMING TO

91       These functions are GNU extensions.
92

NOTES

94       Linking a program with -lmcheck and using the MALLOC_CHECK_ environment
95       variable (described in mallopt(3)) cause the same kinds of errors to be
96       detected.  But, using MALLOC_CHECK_ does not require the application to
97       be relinked.
98

EXAMPLE

100       The  program  below  calls mcheck() with a NULL argument and then frees
101       the same block of memory twice.  The  following  shell  session  demon‐
102       strates what happens when running the program:
103
104           $ ./a.out
105           About to free
106
107           About to free a second time
108           block freed twice
109           Aborted (core dumped)
110
111   Program source
112
113       #include <stdlib.h>
114       #include <stdio.h>
115       #include <mcheck.h>
116
117       int
118       main(int argc, char *argv[])
119       {
120           char *p;
121
122           if (mcheck(NULL) != 0) {
123               fprintf(stderr, "mcheck() failed\n");
124
125               exit(EXIT_FAILURE);
126           }
127
128           p = malloc(1000);
129
130           fprintf(stderr, "About to free\n");
131           free(p);
132           fprintf(stderr, "\nAbout to free a second time\n");
133           free(p);
134
135           exit(EXIT_SUCCESS);
136       }
137

COLOPHON

142       This  page  is  part of release 5.02 of the Linux man-pages project.  A
143       description of the project, information about reporting bugs,  and  the
144       latest     version     of     this    page,    can    be    found    at
145       https://www.kernel.org/doc/man-pages/.
146
147
148
149GNU                               2019-03-06                         MCHECK(3)