MCHECK(3)						     Linux Programmer's Manual							 MCHECK(3)

NAME

       mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap consistency checking

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 malloc(3) family of memory-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 -mcheck inserts an implicit call to mcheck() (with a NULL argument) before the first call	to
       a memory-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 allocated blocks.  This call is  only  effective  if  mcheck()	is  called
       beforehand.

       If  the system detects an inconsistency in the heap, the caller-supplied function pointed to by abortfunc is invoked with a single argument
       argument, mstatus, that indicates what type of inconsistency was detected.  If abortfunc is NULL, a default function prints an  error  mes-
       sage 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 abortfunc 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.

VERSIONS

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

CONFORMING TO

       These functions are GNU extensions.

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.

EXAMPLE

       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 <stdlib.h>
       #include <stdio.h>
       #include <mcheck.h>

       int
       main(int argc, char *argv[])
       {
	   char *p;

	   if (mcheck(NULL) != 0) {
	       fprintf(stderr, "mcheck() failed
");

	       exit(EXIT_FAILURE);
	   }

	   p = malloc(1000);

	   fprintf(stderr, "About to free
");
	   free(p);
	   fprintf(stderr, "
About to free a second time
");
	   free(p);

	   exit(EXIT_SUCCESS);
       }

SEE ALSO

       malloc(3), mallopt(3), mtrace(3)

COLOPHON

       This  page is part of release 3.44 of the Linux man-pages project.  A description of the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.

GNU
								    2012-04-18								 MCHECK(3)