mcheck manpage

Search topic Section

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

       mcheck,	mcheck_check_all,  mcheck_pedantic,  mprobe - heap consistency

       #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);

       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

       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
       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 func-
	      tion was called.	Consistency checking is not possible.

       MCHECK_OK (mprobe() only)
	      No inconsistency detected.

	      Memory preceding an allocated block was clobbered.

	      Memory following an allocated block was clobbered.

	      A block of memory was freed twice.

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

       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

       For   an	  explanation	of   the  terms	 used  in  this	 section,  see

       |Interface		     | Attribute     | Value		     |
       |mcheck(), mcheck_pedantic(), | Thread safety | MT-Unsafe race:mcheck |
       |mcheck_check_all(), mprobe() |		     | const:malloc_hooks    |

       These functions are GNU extensions.

       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.

       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>

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

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


	   p = malloc(1000);

	   fprintf(stderr, "About to free\n");
	   fprintf(stderr, "\nAbout to free a second time\n");


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

       This  page  is  part of release 4.10 of the Linux man-pages project.  A
       description of the project, information about reporting bugs,  and  the
       latest	  version     of     this    page,    can    be	   found    at

GNU				  2015-05-07			     MCHECK(3)