mcheck(3)

✨ mcheck(3) ✨ — heap consistency checking, bestie edition 💖

okay so listen, you know how malloc(3) and its whole friend group can just like… lie to you and corrupt the heap and you'd have NO idea until everything explodes? yeah. that's what these functions are for. this is mcheck(3) and it is lowkey the vibe check your memory has been begging for 🫶

📚 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

so mcheck() installs a set of debugging hooks onto the malloc(3) family of memory-allocation functions — like hiring a security guard for your heap 🧚 and those hooks make certain consistency checks happen on the state of the heap. the checks can catch application errors, like freeing a block of memory more than once, or corrupting the bookkeeping data structures that sit immediately before a block of allocated memory. messy!!

⚠️ to actually be effective, mcheck() has to be called before the first call to malloc(3) or any related function. no exceptions, no "oops I forgot", periodt.

if that's hard to guarantee (it usually is, let's be real 😭), linking the program with -lmcheck inserts an implicit call to mcheck() — with a NULL argument — before the first call to a memory-allocation function. automatic. iconic. 👑

mcheck_pedantic() is basically mcheck() but with main character energy: it performs checks on all allocated blocks whenever one of the memory-allocation functions is called. she does NOT skip leg day.

🐌 heads up bestie: this can be very slow!

mcheck_check_all() causes an immediate check on all allocated blocks. but these instructions are clear — this call is effective only if mcheck() was called beforehand. iykyk.

if the system detects an inconsistency in the heap, the caller-supplied function pointed to by f is invoked with a single argument, mstatus, that tells you what type of inconsistency got detected. and if f is NULL? a default function prints an error message on stderr and calls abort(3). 💀 that's a whole situation.

mprobe() performs a consistency check on the block of allocated memory pointed to by ptr. and yes, mcheck() should be called beforehand — otherwise mprobe() returns MCHECK_DISABLED. it's giving "shoulda planned ahead".

so here's the list of values returned by mprobe() or passed as the mstatus argument when f is invoked — memorize them, there's a quiz later (there is no quiz, but still):

• MCHECK_DISABLED (mprobe() only) — mcheck() was not called before the first memory allocation function was called. consistency checking is not possible. tragic honestly.
• MCHECK_OK (mprobe() only) — no inconsistency detected. she's clean. ✨
• 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. the classic!

🎀 RETURN VALUE

mcheck() and mcheck_pedantic() return 0 on success, or -1 on error. that's it, that's the whole thing.

🔥 ATTRIBUTES

for an explanation of the terms used in this section, go see attributes(7). here's the tea 🍵:

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

⭐ STANDARDS

GNU. (yes, just 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 over in mallopt(3)) cause the same kinds of errors to be detected. the difference? using MALLOC_CHECK_ does not require the application to be relinked. convenient!! 🌈

💖 EXAMPLES

the program below calls mcheck() with a NULL argument and then frees the same block of memory twice. and the following shell session demonstrates what happens when running the program — spoiler alert, it does not end well:

$ ./a.out
About to free

About to free a second time
block freed twice
Aborted (core dumped)

core dumped, bestie. we told her. 😭

🧚 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)

---

okay that's the whole page, no cap 💜 this one was pulled straight out of Linux man-pages 6.20, dated 2026-02-08 — go forth and let your heap be honest for once 🎀✨👑