mcheck(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       int mcheck_pedantic(void (*abortfunc)(enum mcheck_status mstatus));
14       void mcheck_check_all(void);
15
16       enum mcheck_status mprobe(void *ptr);
17

DESCRIPTION

19       The mcheck() function installs a set of debugging hooks  for  the  mal‐
20       loc(3)  family  of memory-allocation functions.  These hooks cause cer‐
21       tain consistency checks to be performed on the state of the heap.   The
22       checks  can detect application errors such as freeing a block of memory
23       more than once or corrupting the bookkeeping data structures that imme‐
24       diately precede a block of allocated memory.
25
26       To  be effective, the mcheck() function must be called before the first
27       call to malloc(3) or a related function.  In cases where this is diffi‐
28       cult  to  ensure, linking the program with -lmcheck inserts an implicit
29       call to mcheck() (with a NULL argument) before the first call to a mem‐
30       ory-allocation function.
31
32       The  mcheck_pedantic()  function  is  similar to mcheck(), but performs
33       checks on all allocated blocks whenever one  of  the  memory-allocation
34       functions is called.  This can be very slow!
35
36       The  mcheck_check_all() function causes an immediate check on all allo‐
37       cated blocks.  This call is effective only if mcheck()  is  called  be‐
38       forehand.
39
40       If the system detects an inconsistency in the heap, the caller-supplied
41       function pointed to by abortfunc is invoked  with  a  single  argument,
42       mstatus,  that  indicates  what type of inconsistency was detected.  If
43       abortfunc is NULL, a default function prints an error message on stderr
44       and calls abort(3).
45
46       The  mprobe() function performs a consistency check on the block of al‐
47       located memory pointed to by ptr.   The  mcheck()  function  should  be
48       called beforehand (otherwise mprobe() returns MCHECK_DISABLED).
49
50       The  following list describes the values returned by mprobe() or passed
51       as the mstatus argument when abortfunc is invoked:
52
53       MCHECK_DISABLED (mprobe() only)
54              mcheck() was not called before the first memory allocation func‐
55              tion was called.  Consistency checking is not possible.
56
57       MCHECK_OK (mprobe() only)
58              No inconsistency detected.
59
60       MCHECK_HEAD
61              Memory preceding an allocated block was clobbered.
62
63       MCHECK_TAIL
64              Memory following an allocated block was clobbered.
65
66       MCHECK_FREE
67              A block of memory was freed twice.
68

RETURN VALUE

70       mcheck() and mcheck_pedantic() return 0 on success, or -1 on error.
71

VERSIONS

73       The  mcheck_pedantic()  and  mcheck_check_all() functions are available
74       since glibc 2.2.  The mcheck() and mprobe() functions are present since
75       at least glibc 2.0
76

ATTRIBUTES

78       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
79       tributes(7).
80
81       ┌─────────────────────────────────┬───────────────┬────────────────────┐
82       │Interface                        │ Attribute     │ Value              │
83       ├─────────────────────────────────┼───────────────┼────────────────────┤
84       │mcheck(), mcheck_pedantic(),     │ Thread safety │ MT-Unsafe          │
85       │mcheck_check_all(), mprobe()     │               │ race:mcheck        │
86       │                                 │               │ const:malloc_hooks │
87       └─────────────────────────────────┴───────────────┴────────────────────┘
88

CONFORMING TO

90       These functions are GNU extensions.
91

NOTES

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

EXAMPLES

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

COLOPHON

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