operator new, operator new[]

void* operator new  ( std::size_t count );

void* operator new[]( std::size_t count );

void* operator new  ( std::size_t count, std::align_val_t al );

void* operator new[]( std::size_t count, std::align_val_t al );

void* operator new  ( std::size_t count, const std::nothrow_t& tag );

void* operator new[]( std::size_t count, const std::nothrow_t& tag );

void* operator new  ( std::size_t count,
                      std::align_val_t al, const std::nothrow_t& );

void* operator new[]( std::size_t count,
                      std::align_val_t al, const std::nothrow_t& );

void* operator new  ( std::size_t count, void* ptr );

void* operator new[]( std::size_t count, void* ptr );

void* operator new  ( std::size_t count, user-defined-args... );

void* operator new[]( std::size_t count, user-defined-args... );

void* operator new  ( std::size_t count,
                      std::align_val_t al, user-defined-args... );

void* operator new[]( std::size_t count, 
                      std::align_val_t al, user-defined-args... );

void* T::operator new  ( std::size_t count );

void* T::operator new[]( std::size_t count );

void* T::operator new  ( std::size_t count, std::align_val_t al );

void* T::operator new[]( std::size_t count, std::align_val_t al );

void* T::operator new  ( std::size_t count, user-defined-args... );

void* T::operator new[]( std::size_t count, user-defined-args... );

void* T::operator new  ( std::size_t count,
                         std::align_val_t al, user-defined-args... );

void* T::operator new[]( std::size_t count,
                         std::align_val_t al, user-defined-args... );

Attempts to allocate requested number of bytes, and the allocation request can fail (even if the requested number of bytes is zero). These allocation functions are called by new-expressions to allocate memory in which new object would then be initialized. They may also be called using regular function call syntax.

Parameters

Return value

Exceptions

Global replacements

The versions (1-4) are implicitly declared in each translation unit even if the <new> header is not included. Versions (1-8) are replaceable: a user-provided non-member function with the same signature defined anywhere in the program, in any source file, replaces the default version. Its declaration does not need to be visible.

The program is ill-formed, no diagnostic required if more than one replacement is provided in the program for any of the replaceable allocation function, or if a replacement is declared with the inline specifier. The program is ill-formed if a replacement is defined in namespace other than global namespace, or if it is defined as a static non-member function at global scope.

The standard library implementations of the nothrow versions (5-8) directly calls the corresponding throwing versions (1-4). The standard library implementation of the throwing array versions (2,4) directly calls the corresponding single-object version (1,3). Thus, replacing the throwing single object allocation functions is sufficient to handle all allocations.

#include <cstdio>
#include <cstdlib>
#include <new>
 
// no inline, required by [replacement.functions]/3
void* operator new(std::size_t sz)
{
    std::printf("1) new(size_t), size = %zu\n", sz);
    if (sz == 0)
        ++sz; // avoid std::malloc(0) which may return nullptr on success
 
    if (void *ptr = std::malloc(sz))
        return ptr;
 
    throw std::bad_alloc{}; // required by [new.delete.single]/3
}
 
// no inline, required by [replacement.functions]/3
void* operator new[](std::size_t sz)
{
    std::printf("2) new[](size_t), size = %zu\n", sz);
    if (sz == 0)
        ++sz; // avoid std::malloc(0) which may return nullptr on success
 
    if (void *ptr = std::malloc(sz))
        return ptr;
 
    throw std::bad_alloc{}; // required by [new.delete.single]/3
}
 
void operator delete(void* ptr) noexcept
{
    std::puts("3) delete(void*)");
    std::free(ptr);
}
 
void operator delete(void* ptr, std::size_t size) noexcept
{
    std::printf("4) delete(void*, size_t), size = %zu\n", size);
    std::free(ptr);
}
 
void operator delete[](void* ptr) noexcept
{
    std::puts("5) delete[](void* ptr)");
    std::free(ptr);
}
 
void operator delete[](void* ptr, std::size_t size) noexcept
{
    std::printf("6) delete[](void*, size_t), size = %zu\n", size);
    std::free(ptr);
}
 
int main()
{
    int* p1 = new int;
    delete p1;
 
    int* p2 = new int[10]; // guaranteed to call the replacement in C++11
    delete[] p2;
}

// Compiled with GCC-5 in C++17 mode to obtain the following:
1) op new(size_t), size = 4
4) op delete(void*, size_t), size = 4
2) op new[](size_t), size = 40
5) op delete[](void* ptr)

Overloads of operator new and operator new[] with additional user-defined parameters ("placement forms", versions (11-14)) may be declared at global scope as usual, and are called by the matching placement forms of new-expressions.

The standard library's non-allocating placement forms of operator new (9-10) cannot be replaced and can only be customized if the placement new-expression did not use the ::new syntax, by providing a class-specific placement new (19,20) with matching signature: void* T::operator new(std::size_t, void*) or void* T::operator new[](std::size_t, void*).

Class-specific overloads

Both single-object and array allocation functions may be defined as public static member functions of a class (versions (15-18)). If defined, these allocation functions are called by new-expressions to allocate memory for single objects and arrays of this class, unless the new expression used the form ::new which bypasses class-scope lookup. The keyword static is optional for these functions: whether used or not, the allocation function is a static member function.

The new expression looks for appropriate allocation function's name firstly in the class scope, and after that in the global scope. Note, that as per name lookup rules, any allocation functions declared in class scope hides all global allocation functions for the new-expressions that attempt to allocate objects of this class.

#include <iostream>
 
// class-specific allocation functions
struct X
{
    static void* operator new(std::size_t count)
    {
        std::cout << "custom new for size " << count << '\n';
        return ::operator new(count);
    }
 
    static void* operator new[](std::size_t count)
    {
        std::cout << "custom new[] for size " << count << '\n';
        return ::operator new[](count);
    }
};
 
int main()
{
    X* p1 = new X;
    delete p1;
    X* p2 = new X[10];
    delete[] p2;
}

custom new for size 1
custom new[] for size 10

Overloads of operator new and operator new[] with additional user-defined parameters ("placement forms"), may also be defined as class members (19-22)). When the placement new expression with the matching signature looks for the corresponding allocation function to call, it begins at class scope before examining the global scope, and if the class-specific placement new is provided, it is called.

#include <iostream>
#include <stdexcept>
 
struct X
{
    X() { throw std::runtime_error(""); }
 
    // custom placement new
    static void* operator new(std::size_t count, bool b)
    {
        std::cout << "custom placement new called, b = " << b << '\n';
        return ::operator new(count);
    }
 
    // custom placement delete
    static void operator delete(void* ptr, bool b)
    {
        std::cout << "custom placement delete called, b = " << b << '\n';
        ::operator delete(ptr);
    }
};
 
int main()
{
    try
    {
        [[maybe_unused]] X* p1 = new (true) X;
    }
    catch (const std::exception&)
    {}
}

custom placement new called, b = 1
custom placement delete called, b = 1

If class-level operator new is a template function, it must have the return type of void*, the first argument std::size_t, and it must have two or more parameters. In other words, only placement forms can be templates.

Notes

Even though the non-allocating placement new (9,10) cannot be replaced, a function with the same signature may be defined at class scope as described above. In addition, global overloads that look like placement new but take a non-void pointer type as the second argument are allowed, so the code that wants to ensure that the true placement new is called (e.g. std::allocator::construct), must use ::new and also cast the pointer to void*.

If the behavior of a deallocation function does not satisfy the default constraints, the behavior is undefined.

It is unspecified whether library versions of operator new make any calls to std::malloc or std::aligned_alloc (since C++17).

For loading a large file, file mapping via OS-specific functions, e.g. mmap on POSIX or CreateFileMapping(A/W) along with MapViewOfFile on Windows, is preferable to allocating a buffer for file reading.

Defect Reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

References

• C++23 standard (ISO/IEC 14882:2023):
• 17.7 Dynamic memory management [support.dynamic]
• C++20 standard (ISO/IEC 14882:2020):
• 17.6 Dynamic memory management [support.dynamic]
• C++17 standard (ISO/IEC 14882:2017):
• 21.6 Dynamic memory management [support.dynamic]
• C++14 standard (ISO/IEC 14882:2014):
• 18.6 Dynamic memory management [support.dynamic]
• C++11 standard (ISO/IEC 14882:2011):
• 18.6 Dynamic memory management [support.dynamic]

See also