mcheck(3) Library Functions Manual mcheck(3)
NAME
mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap consistency
checking
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <mcheck.h>
int mcheck(void (*abortfunc)(enum mcheck_status mstatus));
int mcheck_pedantic(void (*abortfunc)(enum mcheck_status mstatus));
void mcheck_check_all(void);
enum mcheck_status mprobe(void *ptr);
DESCRIPTION
The mcheck() function installs a set of debugging hooks for the mal-
loc(3) family of memory-allocation functions. These hooks cause cer-
tain consistency checks to be performed on the state of the heap. The
checks can detect application errors such as freeing a block of memory
more than once or corrupting the bookkeeping data structures that imme-
diately precede a block of allocated memory.
To be effective, the mcheck() function must be called before the first
call to malloc(3) or a related function. In cases where this is diffi-
cult to ensure, linking the program with -lmcheck inserts an implicit
call to mcheck() (with a NULL argument) before the first call to a mem-
ory-allocation function.
The mcheck_pedantic() function is similar to mcheck(), but performs
checks on all allocated blocks whenever one of the memory-allocation
functions is called. This can be very slow!
The mcheck_check_all() function causes an immediate check on all allo-
cated blocks. This call is effective only if mcheck() is called be-
forehand.
If the system detects an inconsistency in the heap, the caller-supplied
function pointed to by abortfunc is invoked with a single argument,
mstatus, that indicates what type of inconsistency was detected. If
abortfunc is NULL, a default function prints an error message on stderr
and calls abort(3).
The mprobe() function performs a consistency check on the block of al-
located memory pointed to by ptr. The mcheck() function should be
called beforehand (otherwise mprobe() returns MCHECK_DISABLED).
The following list describes the values returned by mprobe() or passed
as the mstatus argument when abortfunc is invoked:
MCHECK_DISABLED (mprobe() only)
mcheck() was not called before the first memory allocation func-
tion was called. Consistency checking is not possible.
MCHECK_OK (mprobe() only)
No inconsistency detected.
MCHECK_HEAD
Memory preceding an allocated block was clobbered.
MCHECK_TAIL
Memory following an allocated block was clobbered.
MCHECK_FREE
A block of memory was freed twice.
RETURN VALUE
mcheck() and mcheck_pedantic() return 0 on success, or -1 on error.
ATTRIBUTES
For an explanation of the terms used in this section, see attrib-
utes(7).
┌────────────────────────────────┬───────────────┬────────────────────┐
│ Interface │ Attribute │ Value │
├────────────────────────────────┼───────────────┼────────────────────┤
│ mcheck(), mcheck_pedantic(), │ Thread safety │ MT-Unsafe │
│ mcheck_check_all(), mprobe() │ │ race:mcheck │
│ │ │ const:malloc_hooks │
└────────────────────────────────┴───────────────┴────────────────────┘
STANDARDS
GNU.
HISTORY
mcheck_pedantic()
mcheck_check_all()
glibc 2.2.
mcheck()
mprobe()
glibc 2.0.
NOTES
Linking a program with -lmcheck and using the MALLOC_CHECK_ environment
variable (described in mallopt(3)) cause the same kinds of errors to be
detected. But, using MALLOC_CHECK_ does not require the application to
be relinked.
EXAMPLES
The program below calls mcheck() with a NULL argument and then frees
the same block of memory twice. The following shell session demon-
strates what happens when running the program:
$ ./a.out
About to free
About to free a second time
block freed twice
Aborted (core dumped)
Program source
#include <mcheck.h>
#include <stdio.h>
#include <stdlib.h>
int
main(void)
{
char *p;
if (mcheck(NULL) != 0) {
fprintf(stderr, "mcheck() failed\n");
exit(EXIT_FAILURE);
}
p = malloc(1000);
fprintf(stderr, "About to free\n");
free(p);
fprintf(stderr, "\nAbout to free a second time\n");
free(p);
exit(EXIT_SUCCESS);
}
SEE ALSO
malloc(3), mallopt(3), mtrace(3)
Linux man-pages 6.7 2024-02-26 mcheck(3)
Generated by dwww version 1.16 on Tue Dec 16 11:12:23 CET 2025.