mcheck(3) — Linux manual page

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ATTRIBUTES | STANDARDS | HISTORY | NOTES | EXAMPLES | SEE ALSO | COLOPHON

mcheck(3)               Library Functions Manual               mcheck(3)

NAME         top

       mcheck, mcheck_check_all, mcheck_pedantic, mprobe - heap
       consistency checking

LIBRARY         top

       Standard C library (libc, -lc)

SYNOPSIS         top

       #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         top

       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 -lmcheck
       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 effective only 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, 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
              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         top

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

ATTRIBUTES         top

       For an explanation of the terms used in this section, see
       attributes(7).
       ┌──────────────────────────┬───────────────┬────────────────────┐
       │ Interface                Attribute     Value              │
       ├──────────────────────────┼───────────────┼────────────────────┤
       │ mcheck(),                │ Thread safety │ MT-Unsafe          │
       │ mcheck_pedantic(),       │               │ race:mcheck        │
       │ mcheck_check_all(),      │               │ const:malloc_hooks │
       │ mprobe()                 │               │                    │
       └──────────────────────────┴───────────────┴────────────────────┘

STANDARDS         top

       GNU.

HISTORY         top

       mcheck_pedantic()
       mcheck_check_all()
              glibc 2.2.

       mcheck()
       mprobe()
              glibc 2.0.

NOTES         top

       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         top

       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\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         top

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

COLOPHON         top

       This page is part of the man-pages (Linux kernel and C library
       user-space interface documentation) project.  Information about
       the project can be found at 
       ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report
       for this manual page, see
       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
       This page was obtained from the tarball man-pages-6.9.1.tar.gz
       fetched from
       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
       2024-06-26.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-
       to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not
       part of the original manual page), send a mail to
       man-pages@man7.org

Linux man-pages 6.9.1          2024-06-15                      mcheck(3)

Pages that refer to this page: malloc(3)malloc_hook(3)mallopt(3)mtrace(3)