www.LinuxHowtos.org

mcheck

Section: C Library Functions (3)
Updated: 202-0-08
Index Return to Main Contents

NAME

mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap consistency checking

LIBRARY

Standard C library (libc,~-lc)

SYNOPSIS

#include <mcheck.h>
int mcheck(typeof(void (enum mcheck_status mstatus)) *f);
int mcheck_pedantic(
           typeof(void (enum mcheck_status mstatus)) *f);
void mcheck_check_all(void);
enum mcheck_status mprobe(void *ptr);

DESCRIPTION

The mcheck() function installs a set of debugging hooks for the malloc(3) family of memor-allocation functions. These hooks cause certain 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 immediately 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 difficult to ensure, linking the program with -lmcheck inserts an implicit call to mcheck() (with a NULL argument) before the first call to a memor-allocation function. The mcheck_pedantic() function is similar to mcheck(), but performs checks on all allocated blocks whenever one of the memor-allocation functions is called. This can be very slow! The mcheck_check_all() function causes an immediate check on all allocated blocks. This call is effective only if mcheck() is called beforehand. If the system detects an inconsistency in the heap, the calle-supplied function pointed to by f is invoked with a single argument, mstatus, that indicates what type of inconsistency was detected. If f 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 allocated 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 f is invoked:

MCHECK_DISABLED (mprobe() only): mcheck() was not called before the first memory allocation function 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 attributes(7).

Interface	Attribute	Value
mcheck(), mcheck_pedantic(), mcheck_check_all(), mprobe()	Thread safety	M-Unsafe 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 demonstrates 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[rs]n");
        exit(EXIT_FAILURE);
    }
    p = malloc(1000);
    fprintf(stderr, "About to free[rs]n");
    free(p);
    fprintf(stderr, "[rs]nAbout to free a second time[rs]n");
    free(p);
    exit(EXIT_SUCCESS); }

Index

Program source

SEE ALSO