mprobe(3)

1mcheck(3)                  Library Functions Manual                  mcheck(3)
2
3
4

NAME

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

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ATTRIBUTES

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

STANDARDS

88       GNU.
89

HISTORY

91       mcheck_pedantic()
92       mcheck_check_all()
93              glibc 2.2.
94
95       mcheck()
96       mprobe()
97              glibc 2.0.
98

NOTES

100       Linking a program with -lmcheck and using the MALLOC_CHECK_ environment
101       variable (described in mallopt(3)) cause the same kinds of errors to be
102       detected.  But, using MALLOC_CHECK_ does not require the application to
103       be relinked.
104

EXAMPLES

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