operator new, operator new[]

Header: <new>

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.

# Declarations

Replaceable allocation functions

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

(since C++17)

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

(since C++17)

Replaceable non-throwing allocation functions

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

(noexcept since C++11)

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

(noexcept since C++11)

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

(since C++17)

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

(since C++17)

Non-allocating placement allocation functions

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

(noexcept since C++11) (constexpr since C++26)

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

(noexcept since C++11) (constexpr since C++26)

User-defined placement allocation functions

void* operator new ( std::size_t count, /* args... */ );

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

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

(since C++17)

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

(since C++17)

Class-specific allocation functions

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

(since C++17)

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

(since C++17)

Class-specific placement allocation functions

void* T::operator new ( std::size_t count, /* args... */ );

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

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

(since C++17)

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

(since C++17)

# Parameters

• count: number of bytes to allocate
• ptr: pointer to a memory area to initialize the object at
• tag: disambiguation tag used to select non-throwing overloads
• al: alignment to use, invalid value leads to undefined behavior

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

The following functions are required to be thread-safe:

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.

It is unspecified whether library versions of operator new make any calls to std::mallocor 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

# See also

• operator new
• operator deleteoperator delete[]
• get_new_handler
• set_new_handler
• get_temporary_buffer
• malloc
• aligned_alloc