View source for cpp/memory/new/operator new

You do not have permission to edit this page, for the following reasons:

The action you have requested is limited to users in one of the groups: Users, Administrators.

Due to recent vandalism, editing of this page is temporarily disabled for new users.If you want to suggest a change, please leave a message on the suggestions page for new users instead (don't be surprised if that page appears vandalized!).

You can view and copy the source of this page.

{{title|{{small|operator}} new{{small|, operator}} new[]}}
{{cpp/memory/new/navbar}}
{{dcl begin}}
{{dcl header|new}}
{{dcl h|Replaceable allocation functions}}
{{dcla|num=1|
void* operator new  ( std::size_t count );
}}
{{dcla|num=2|
void* operator new[]( std::size_t count );
}}
{{dcla|num=3|since=c++17|
void* operator new  ( std::size_t count, std::align_val_t al );
}}
{{dcla|num=4|since=c++17|
void* operator new[]( std::size_t count, std::align_val_t al );
}}
{{dcl h|Replaceable non-throwing allocation functions}}
{{dcla|num=5|noexcept=c++11|
void* operator new  ( std::size_t count, const std::nothrow_t& tag );
}}
{{dcla|num=6|noexcept=c++11|
void* operator new[]( std::size_t count, const std::nothrow_t& tag );
}}
{{dcla|num=7|since=c++17|
void* operator new  ( std::size_t count, std::align_val_t al,
                      const std::nothrow_t& tag ) noexcept;
}}
{{dcla|num=8|since=c++17|
void* operator new[]( std::size_t count, std::align_val_t al,
                      const std::nothrow_t& tag ) noexcept;
}}
{{dcl h|Non-allocating placement allocation functions}}
{{dcla|num=9|noexcept=c++11|constexpr=c++26|
void* operator new  ( std::size_t count, void* ptr );
}}
{{dcla|num=10|noexcept=c++11|constexpr=c++26|
void* operator new[]( std::size_t count, void* ptr );
}}
{{dcl h|User-defined placement allocation functions}}
{{dcla|num=11|
void* operator new  ( std::size_t count, /* args... */ );
}}
{{dcla|num=12|
void* operator new[]( std::size_t count, /* args... */ );
}}
{{dcla|num=13|since=c++17|
void* operator new  ( std::size_t count,
                      std::align_val_t al, /* args... */ );
}}
{{dcla|num=14|since=c++17|
void* operator new[]( std::size_t count,
                      std::align_val_t al, /* args... */ );
}}
{{dcl h|Class-specific allocation functions}}
{{dcla|num=15|
void* T::operator new  ( std::size_t count );
}}
{{dcla|num=16|
void* T::operator new[]( std::size_t count );
}}
{{dcla|num=17|since=c++17|
void* T::operator new  ( std::size_t count, std::align_val_t al );
}}
{{dcla|num=18|since=c++17|
void* T::operator new[]( std::size_t count, std::align_val_t al );
}}
{{dcl h|Class-specific placement allocation functions}}
{{dcla|num=19|
void* T::operator new  ( std::size_t count, /* args... */ );
}}
{{dcla|num=20|
void* T::operator new[]( std::size_t count, /* args... */ );
}}
{{dcla|num=21|since=c++17|
void* T::operator new  ( std::size_t count,
                         std::align_val_t al, /* args... */ );
}}
{{dcla|num=22|since=c++17|
void* T::operator new[]( std::size_t count,
                         std::align_val_t al, /* args... */ );
}}
{{dcl end}}

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 [[cpp/language/new|{{c/core|new}} expressions]] to allocate memory in which new object would then be initialized. They may also be called using regular function call syntax.

@1-8@ [[cpp/language/replacement function|Replaceable]] allocation functions. The standard library provides default implementations for these functions, for the effects of the default implementations, see [[#Global replacement|below]].

@9,10@ Called by the standard [[cpp/language/new#Placement new|placement {{c/core|new}} expressions]]. Performs no action and returns {{c|ptr}} unmodified.
@@ If this function is called through placement {{c/core|new}} and {{c|ptr}} is a null pointer, the behavior is undefined.<!-- CWG 1748 -->

@11-22@ User-defined allocation functions called by {{c/core|new}} expressions.

Overloads {{vl|1-4}} are implicitly declared in each translation unit even if the {{header|new}} header is not included.

See [[cpp/language/new|{{c/core|new}} expression]] for the criteria of selecting overload.

===Parameters===
{{par begin}}
{{par|count|number of bytes to allocate}}
{{par|ptr|pointer to a memory area to initialize the object at}}
{{par|tag|disambiguation tag used to select non-throwing overloads}}
{{par|al|alignment to use, invalid value leads to undefined behavior}}
{{par end}}

===Return value===
@1-4@ If the allocation succeeds, a non-null pointer {{c|p0}} which points to suitably aligned memory of size at least {{c|size}} and is different from any previously returned value {{c|p1}}, unless that value {{c|p1}} was subsequently passed to a replaceable {{rlp|operator delete|deallocation function}}; if the allocation fails, does not return (an exception is thrown, see below).

@5-8@ Same as {{vl|1-4}}, but returns a null pointer if the allocation fails.

@9,10@ {{c|ptr}}

@11-22@ Same as {{vl|1-4}} if the function does not return on allocation failure, otherwise same as {{vl|5-8}}.

===Exceptions===
@1-4@ Throws an exception of a type that would match a handler of type {{lc|std::bad_alloc}} on failure to allocate memory.

@11-22@ Same as {{vl|1-4}} if the function does not return on allocation failure, otherwise same as {{vl|5-8}}.

===Global replacements===
Overloads {{vl|1-8}} are [[cpp/language/replacement function|replaceable]]. The effects of the default versions are:

@1@ Attempts to allocate the requested storage. Whether the attempt involves a call to {{lc|std::malloc}} or {{lc|std::aligned_alloc}} is unspecified.
* If the attempt is successful, returns a pointer to the allocated storage.
* Otherwise, if currently no {{rlp|set_new_handler|new-handler}} is installed, throws {{lc|std::bad_alloc}}.
* Otherwise, calls the currently installed new-handler.
** If the new-handler returns, starts another allocation attempt.
** Otherwise, exits the current invocation.

@2@ Returns {{c|operator new(count)}}.

@3@ Same as {{v|1}}.

@4@ Returns {{c|operator new(count, al)}}.

@5-8@ Calls {{v|1-4}} respectively with the same arguments except for {{c|tag}}.
* If the call returns normally, returns the result of that call.
* Otherwise, returns a null pointer.

{{rrev|since=c++26|
On [[cpp/freestanding|freestanding implementations]], it is implementation-defined whether the default versions of {{vl|1-8}} satisfy the behaviors required above. Freestanding implementations are recommended that if any of these default versions meet the requirements of a hosted implementation, they all should.
}}

{{cpp/memory/new/minimal replacement example}}

Overloads of {{tt|operator new}} and {{tt|operator new[]}} with additional user-defined parameters ("placement forms", versions {{vl|11-14}}) may be declared at global scope as usual, and are called by the matching [[cpp/language/new#Placement new|placement forms]] of {{c/core|new}} expressions.

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

{{rrev|since=c++14|
The placement form {{c/core|void* operator new(std::size_t, std::size_t)}} is not allowed because the matching signature of the deallocation function, {{c/core|void operator delete(void*, std::size_t)}}, is a usual (not placement) deallocation function.
}}

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

The {{c/core|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 [[cpp/language/lookup|name lookup rules]], any allocation functions declared in class scope hides all global allocation functions for the {{c/core|new}} expressions that attempt to allocate objects of this class.

{{rrev|since=c++17|
When allocating objects and arrays of objects whose alignment exceeds {{c|__STDCPP_DEFAULT_NEW_ALIGNMENT__}}, overload resolution is performed twice: first, for alignment-aware function signatures, then for alignment-unaware function signatures. This means that if a class with extended alignment has an alignment-unaware class-specific allocation function, it is the function that will be called, not the global alignment-aware allocation function. This is intentional: the class member is expected to know best how to handle that class.
}}

{{rrev|since=c++20|
When allocating objects and arrays of objects whose alignment does not exceed {{c|__STDCPP_DEFAULT_NEW_ALIGNMENT__}}, overload resolution is performed twice: first, for alignment-unaware function signatures, then for alignment-aware function signatures.
}}

{{example
|code=
#include <cstddef>
#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;
}
|p=true
|output=
custom new for size 1
custom new[] for size 10
}}

Overloads of {{tt|operator new}} and {{tt|operator new[]}} with additional user-defined parameters ("placement forms"), may also be defined as class members {{vl|19-22}}). When the placement {{c/core|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 {{c/core|new}} is provided, it is called.

{{rrev|since=c++17|
When allocating objects and arrays of objects whose alignment exceeds {{c|__STDCPP_DEFAULT_NEW_ALIGNMENT__}}, overload resolution for placement forms is performed twice just as for regular forms: first, for alignment-aware function signatures, then for alignment-unaware function signatures.
}}

{{rrev|since=c++20|
When allocating objects and arrays of objects whose alignment does not exceed {{c|__STDCPP_DEFAULT_NEW_ALIGNMENT__}}, overload resolution for placement forms is performed twice just as for regular forms: first, for alignment-unaware function signatures, then for alignment-aware function signatures.
}}

{{example
|code=
#include <cstddef>
#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&)
    {}
}
|output=
custom placement new called, b = 1
custom placement delete called, b = 1
}}

If class-level {{tt|operator new}} is a template function, it must have the return type of {{c/core|void*}}, the first argument {{lc|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 {{c/core|new}} {{vl|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 {{c/core|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 {{c/core|new}} is called (e.g. {{lc|std::allocator::construct}}), must use {{c/core|::new}} and also cast the pointer to {{c/core|void*}}.

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

{{cpp/memory/thread safety note}}

It is unspecified whether library versions of {{tt|operator new}} make any calls to {{lc|std::malloc}}{{rev inl|since=c++17| or {{lc|std::aligned_alloc}}}}.

For loading a large file, file mapping via OS-specific functions, e.g., {{posix|mmap}} on POSIX or {{tt|CreateFileMapping}}([https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createfilemappinga {{tt|A}}]/[https://learn.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-createfilemappingw {{tt|W}}]) along with [https://learn.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-mapviewoffile {{tt|MapViewOfFile}}] on Windows, is preferable to allocating a buffer for file reading.

{{ftm begin}}
{{ftm|__cpp_lib_freestanding_operator_new|rowspan=2|value=202306L|std=C++26|freestanding support for replaceable {{c/core|operator new}}<ref>Formally, this macro expands to {{c|202306L}} if all the default versions of the replaceable global allocation functions meet the requirements of a hosted implementation.</ref>}}
{{ftm|-|value=0|std=C++26|no freestanding support}}
{{ftm|__cpp_lib_constexpr_new|value=202406L|std=C++26|{{c/core|constexpr}} placement {{c/core|new}} and {{c/core|new[]}}}}
{{ftm end}}
<references/>

===Defect reports===
{{dr list begin}}
{{dr list item|wg=cwg|dr=521|std=C++98|before=any class derived from {{lc|std::bad_alloc}} could be thrown,<br>even if the {{lc|std::bad_alloc}} base is ambiguous or inaccessible|after=the exception thrown should match<br>a handler of type {{lc|std::bad_alloc}}}}
{{dr list item|wg=lwg|dr=9|std=C++98|before=multiple calls for allocating zero<br>bytes could yield the same pointer|after=only allowed if all such previously<br>yielded pointers have been<br>passed to deallocation functions}}
{{dr list item|wg=lwg|dr=206|std=C++98|before=replacing the replaceable allocation functions did<br>not affect the default behaviors of the corresponding<br>replaceable non-throwing allocation functions|after=the default behaviors<br>change accordingly}}
{{dr list item|wg=lwg|dr=404|std=C++98|before=replacements of the replaceable allocation<br>functions could be declared {{c/core|inline}}|after=prohibited, no diagnostic required}}
{{dr list end}}

===References===
{{ref std c++23}}
{{ref std|section=17.7|title=Dynamic memory management|id=support.dynamic}}
{{ref std end}}
{{ref std c++20}}
{{ref std|section=17.6|title=Dynamic memory management|id=support.dynamic}}
{{ref std end}}
{{ref std c++17}}
{{ref std|section=21.6|title=Dynamic memory management|id=support.dynamic}}
{{ref std end}}
{{ref std c++14}}
{{ref std|section=18.6|title=Dynamic memory management|id=support.dynamic}}
{{ref std end}}
{{ref std c++11}}
{{ref std|section=18.6|title=Dynamic memory management|id=support.dynamic}}
{{ref std end}}
{{ref std c++03}}
{{ref std|section=18.4|title=Dynamic memory management|id=lib.support.dynamic}}
{{ref std end}}
{{ref std c++98}}
{{ref std|section=18.4|title=Dynamic memory management|id=lib.support.dynamic}}
{{ref std end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/coroutine/generator/promise_type/dsc operator new}}
{{dsc inc|cpp/memory/new/dsc operator_delete}}
{{dsc inc|cpp/memory/new/dsc get_new_handler}}
{{dsc inc|cpp/memory/new/dsc set_new_handler}}
{{dsc inc|cpp/memory/dsc get_temporary_buffer}}
{{dsc inc|cpp/memory/c/dsc malloc}}
{{dsc inc|cpp/memory/c/dsc aligned_alloc}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Templates used on this page:

Template:!! (view source)
Template:anchor (view source)
Template:c (view source) (protected)
Template:c/core (view source) (protected)
Template:cmark (view source) (protected)
Template:cmark static (view source) (protected)
Template:co (view source)
Template:cpp/coroutine/generator/promise type/dsc operator new (view source)
Template:cpp/coroutine/generator/promise type/title (view source)
Template:cpp/memory/c/dsc aligned alloc (view source)
Template:cpp/memory/c/dsc malloc (view source)
Template:cpp/memory/dsc get temporary buffer (view source)
Template:cpp/memory/navbar content (view source)
Template:cpp/memory/navbar heading (view source)
Template:cpp/memory/new/dsc get new handler (view source)
Template:cpp/memory/new/dsc operator delete (view source)
Template:cpp/memory/new/dsc set new handler (view source)
Template:cpp/memory/new/minimal replacement example (view source)
Template:cpp/memory/new/navbar (view source)
Template:cpp/memory/new/navbar content (view source)
Template:cpp/memory/new/navbar heading (view source)
Template:cpp/memory/thread safety note (view source)
Template:cpp/navbar content (view source)
Template:cpp/navbar heading (view source)
Template:cpp/title (view source) (protected)
Template:cpp/utility/navbar content (view source)
Template:cpp/utility/navbar heading (view source)
Template:ctitle (view source) (protected)
Template:dcl/std (view source) (semi-protected)
Template:dcl begin (view source) (protected)
Template:dcl end (view source) (protected)
Template:dcl h (view source) (protected)
Template:dcl header (view source) (protected)
Template:dcl list header/link (view source)
Template:dcl sep (view source) (protected)
Template:dcla (view source)
Template:dr list begin (view source)
Template:dr list end (view source)
Template:dr list item (view source)
Template:dsc (view source) (protected)
Template:dsc begin (view source) (protected)
Template:dsc editlink (view source)
Template:dsc end (view source) (protected)
Template:dsc fun (view source) (protected)
Template:dsc guard (view source) (protected)
Template:dsc header/link (view source)
Template:dsc inc (view source) (protected)
Template:dsc mark mem (view source) (protected)
Template:dsc mem sfun (view source) (protected)
Template:dsc member (view source) (protected)
Template:dsc tfun (view source) (protected)
Template:example (view source) (protected)
Template:ftm (view source)
Template:ftm begin (view source)
Template:ftm end (view source)
Template:ftm link (view source)
Template:get lang (view source) (protected)
Template:get lang formal (view source)
Template:header (view source)
Template:l2tt/core (view source) (protected)
Template:langlinks (view source) (protected)
Template:langlinks/one (view source) (protected)
Template:lc (view source) (protected)
Template:lines (view source) (protected)
Template:ls (view source)
Template:lsd (view source)
Template:ltt (view source) (protected)
Template:ltt/core (view source) (protected)
Template:mark (view source) (protected)
Template:mark c++11 (view source) (protected)
Template:mark c++14 (view source) (protected)
Template:mark c++17 (view source) (protected)
Template:mark c++20 (view source)
Template:mark c++23 (view source) (protected)
Template:mark c++26 (view source)
Template:mark constexpr since c++26 (view source)
Template:mark deprecated c++20 (view source)
Template:mark expos (view source)
Template:mark expos/core (view source)
Template:mark fun (view source) (protected)
Template:mark mem sfun (view source) (protected)
Template:mark noexcept since c++11 (view source)
Template:mark rev (view source) (protected)
Template:mark since c++11 (view source) (protected)
Template:mark since c++14 (view source) (protected)
Template:mark since c++17 (view source)
Template:mark since c++20 (view source)
Template:mark since c++26 (view source)
Template:mark tfun (view source) (protected)
Template:mark tooltip (view source)
Template:mark until c++20 (view source)
Template:mark until c++23 (view source)
Template:navbar (view source)
Template:navbar editlink (view source) (protected)
Template:nbsp (view source) (protected)
Template:nbspt (view source)
Template:nv (view source) (protected)
Template:nv begin (view source) (protected)
Template:nv col begin (view source) (protected)
Template:nv col end (view source) (protected)
Template:nv col next (view source) (protected)
Template:nv end (view source) (protected)
Template:nv h1 (view source) (protected)
Template:nv h2 (view source) (protected)
Template:nv ln (view source) (protected)
Template:nv mem ln (view source) (protected)
Template:nv ph (view source)
Template:par (view source) (protected)
Template:par begin (view source) (protected)
Template:par end (view source) (protected)
Template:posix (view source)
Template:posix/core (view source)
Template:ref std (view source)
Template:ref std c++03 (view source)
Template:ref std c++11 (view source)
Template:ref std c++14 (view source)
Template:ref std c++17 (view source)
Template:ref std c++20 (view source)
Template:ref std c++23 (view source)
Template:ref std c++98 (view source)
Template:ref std end (view source)
Template:rev (view source) (protected)
Template:rev begin (view source)
Template:rev end (view source)
Template:rev inl (view source)
Template:rlp (view source) (protected)
Template:rrev (view source)
Template:small (view source) (protected)
Template:source (view source) (protected)
Template:title (view source) (protected)
Template:tooltip (view source)
Template:trim (view source) (protected)
Template:tt (view source) (protected)
Template:v (view source)
Template:vl (view source)

Return to cpp/memory/new/operator new.

cppreference.com

Search

Namespaces

Variants

Views

Actions

View source for cpp/memory/new/operator new

Navigation

Tools