std::free(3)

✨ NAME ✨

std::free - std::free. Yep bestie, that's the NAME line — it's literally the same thing twice. This is the std::free(3) page from the C++ Standard Library (the header spells it C++ Standard Libary, and I'm not correcting it; we respect the typo 😌).

🦋 Synopsis 🦋

Defined in header <cstdlib>:

Defined in header <cstdlib>
void free( void* ptr );

Deallocates the space previously allocated by std::malloc, std::calloc, std::aligned_alloc (since C++17), or std::realloc. That's the whole assignment. Cleanup era 💅.

If ptr is a null pointer, the function does nothing. Null? Cute. No work today.

🚨 The behavior is undefined if the value of ptr does not equal a value returned earlier by std::malloc, std::calloc, std::aligned_alloc (since C++17), or std::realloc.

🚨 The behavior is undefined if the memory area referred to by ptr has already been deallocated, that is, std::free or std::realloc has already been called with ptr as the argument and no calls to std::malloc, std::calloc, std::aligned_alloc (since C++17), or std::realloc resulted in a pointer equal to ptr afterwards.

🚨 The behavior is undefined if after std::free returns, an access is made through the pointer ptr (unless another allocation function happened to result in a pointer value equal to ptr).

The following functions are required to be thread-safe:

• The library versions of operator new and operator delete
• User replacement versions of global operator new and operator delete
• std::calloc, std::malloc, std::realloc (since C++11), std::aligned_alloc (since C++17), std::free

Calls to these functions that allocate or deallocate a particular unit of storage occur in a single total order, and each such deallocation call happens-before the next allocation (if any) in this order. No cap, that's the ordering tea ☕.

🌸 Parameters 🌸

• ptr — pointer to the memory to deallocate.

🎀 Return value 🎀

(none) — the section literally says (none). No return value, no drama, just vibes.

💜 Notes 💜

The function accepts (and does nothing with) the null pointer to reduce the amount of special-casing. Whether allocation succeeds or not, the pointer returned by an allocation function can be passed to std::free. So yes, the null pointer is invited to the function and gets to chill 🫶.

🔥 Example 🔥

Run this code, bestie:

// Run this code

#include <cstdlib>

int main()
{
    int* p1 = (int*)std::malloc(10 * sizeof *p1);
    std::free(p1); // every allocated pointer must be freed

    int* p2 = (int*)std::calloc(10, sizeof *p2);
    int* p3 = (int*)std::realloc(p2, 1000 * sizeof *p3);
    if (!p3) // p3 null means realloc failed and p2 must be freed.
        std::free(p2);
    std::free(p3); // p3 can be freed whether or not it is null.
}

🌈 See also 🌈

• C documentation for free

---

source: http://cppreference.com • version/date: 2024.06.10 • page: std::free(3) — bye bestie, go free your pointers (the valid ones, okay?) 💖✨