# <new>

<head><title>&lt;new&gt;</title></head>

# `<new>`

* * *

Include the standard header **`<new>`**
to define several types and functions that control allocation and
freeing of storage under program control.

Some of the functions declared in this header are
**replaceable**.
The implementation supplies a default version, whose behavior is
described in this document. A program can, however, define a
function with the same signature to replace the default version
at link time. The replacement version must satisfy the requirements
described in this document.

    namespace std {
    typedef void (*new_handler)();
    class bad_alloc;
    class nothrow_t;
    extern const nothrow_t nothrow;
    
            // FUNCTIONS
    new_handler set_new_handler(new_handler pnew) throw();
        };
    
            // OPERATORS -- NOT IN NAMESPACE std
    void operator delete(void *ptr) throw();  // REPLACEABLE
    void operator delete(void *, void *) throw();
    void operator delete(void *ptr,  // REPLACEABLE
        const std::nothrow_t&) throw();
    void operator delete[](void *ptr) throw();  // REPLACEABLE
    void operator delete[](void *, void *) throw();
    void operator delete[](void *ptr,  // REPLACEABLE
        const std::nothrow_t&) throw();
    void *operator new(std::size_t count)  // REPLACEABLE
        throw(std::bad_alloc);
    void *operator new(std::size_t count,  // REPLACEABLE
        const std::nothrow_t&) throw();
    void *operator new(std::size_t count, void *ptr) throw();
    void *operator new[](std::size_t count)  // REPLACEABLE
        throw(std::bad_alloc);
    void *operator new[](std::size_t count,  // REPLACEABLE
        const std::nothrow_t&) throw();
    void *operator new[](std::size_t count, void *ptr) throw();Copy to clipboard

## `bad_alloc`

    class bad_alloc : public exception {
    }  // namespace stdCopy to clipboard

The class describes an exception thrown to indicate that
an allocation request did not succeed. The value returned by
`what()`
is an implementation-defined
[C string](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_over.html#C%20string).
None of the member functions throw any exceptions.

## `new_handler`

    typedef void (*new_handler)();Copy to clipboard

The type describes a pointer object that
designates a function suitable for use as a
[new handler](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#new%20handler).

## `nothrow`

    extern const nothrow_t nothrow;Copy to clipboard

The object is used as a function argument to
match the parameter type
`nothrow_t`.

## `nothrow_t`

    class nothrow_t {};Copy to clipboard

The class is used as a function parameter to
`operator new` to indicate that the function should
return a null pointer to report an allocation failure,
rather than throw an exception.

## `operator delete`

    void operator delete(void *ptr) throw();  // REPLACEABLE
    void operator delete(void *, void *) throw();
    void operator delete(void *ptr,  // REPLACEABLE
        const std::nothrow_t&) throw();Copy to clipboard

The first function is called by a
**`delete` expression**
to render the value of `ptr` invalid.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
`ptr` that is null or that was returned by an earlier call to
`operator new(size_t)`.

The default behavior for a null value of `ptr` is
to do nothing. Any other value of `ptr` must be a value returned
earlier by a call as described above.
The default behavior for such a non-null value of `ptr` is to
reclaim storage allocated by the earlier call.
It is unspecified under what conditions part or all
of such reclaimed storage is allocated by a subsequent call to
`operator new(size_t)`,
or to any of
`calloc(size_t)`,
`malloc(size_t)`, or
`realloc(void*, size_t)`.

The second function is called by a
**placement`delete` expression** corresponding to a
[`new` expression](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#new%20expression)
of the form
`new(std::size_t)`.
It does nothing.

The third function is called by a placement
`delete` expression corresponding to a
`new` expression of the form
`new(std::size_t, const std::nothrow_t&)`.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
`ptr` that is null or that was returned by an earlier call to
`operator new(size_t)`.
The default behavior is to evaluate `delete(ptr)`.

## `operator delete[]`

    void operator delete[](void *ptr) throw();  // REPLACEABLE
    void operator delete[](void *, void *) throw();
    void operator delete[](void *ptr,  // REPLACEABLE
        const std::nothrow_t&) throw();Copy to clipboard

The first function is called by a
**`delete[]` expression**
to render the value of `ptr` invalid.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the
Standard C++ library.

The required behavior is to accept a value of `ptr`
that is null or that was returned by an earlier call to
`operator new[](size_t)`.
The default behavior is to evaluate `delete(ptr)`.

The second function is called by a
**placement`delete[]` expression** corresponding to a
[`new\[\]` expression](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#new[]%20expression) of the form
`new[](std::size_t)`.
It does nothing.

The third function is called by a placement
`delete` expression corresponding to a
`new[]` expression of the form
`new[](std::size_t, const std::nothrow_t&)`.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the
Standard C++ library. The required behavior is to accept a value of
`ptr` that is null or that was returned by an earlier call to
`operator new[](size_t)`.
The default behavior is to call
`operator delete(ptr, std::nothrow)`.

## `operator new`

    void *operator new(std::size_t count) throw(bad_alloc);  // REPLACEABLE
    void *operator new(std::size_t count,  // REPLACEABLE
        const std::nothrow_t&) throw();
    void *operator new(std::size_t count, void *ptr) throw();Copy to clipboard

The first function is called by a
**`new` expression**
to allocate `count` bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the Standard C++ library.

The required behavior is to return a non-null pointer only
if storage can be allocated as requested. Each such allocation
yields a pointer to storage disjoint from any other allocated storage.
The order and contiguity of storage allocated by successive calls
is unspecified. The initial stored value is unspecified.
The returned pointer designates the start (lowest
byte address) of the allocated storage. If `count` is zero, the
value returned does not compare equal to any other value returned
by the function.

The default behavior is to execute a loop. Within the loop,
the function first attempts to allocate the requested storage. Whether
the attempt involves a call to
`malloc(size_t)`
is unspecified. If the attempt is successful, the function returns
a pointer to the allocated storage.
Otherwise, the function calls the designated
[new handler](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#new%20handler). If the
called function returns, the loop repeats. The loop terminates when
an attempt to allocate the requested storage is successful or when
a called function does not return.

The required behavior of a
**new handler**
is to perform one of the following operations:

- make more storage available for allocation and then return
- call either
`abort()` or
`exit(int)`
- throw an object of type
[`bad_alloc`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#bad_alloc)

The default behavior of a
[new handler](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#new%20handler) is to throw an object of type
`bad_alloc`. A null pointer designates the default
new handler.

The order and contiguity of storage allocated by successive
calls to `operator new(size_t)` is unspecified,
as are the initial values stored there.

The second function:

    void *operator new(std::size_t count,
        const std::nothrow_t&) throw();Copy to clipboard

is called by a
[placement
`new` expression](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#placement%20new%20expression)
to allocate `count` bytes of storage
suitably aligned to represent any object of that size.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the Standard C++ library.

The default behavior is to return
`operator new(count)` if that
function succeeds. Otherwise, it returns a null pointer.

The third function:

    void *operator new(std::size_t count, void *ptr) throw();Copy to clipboard

is called by a
**placement `new` expression**,
of the form `new (args) T`.
Here, `args` consists of a single object pointer.
The function returns `ptr`.

## `operator new[]`

    void *operator new[](std::size_t count)  // REPLACEABLE
        throw(std::bad_alloc);
    void *operator new[](std::size_t count,  // REPLACEABLE
        const std::nothrow_t&) throw();
    void *operator new[](std::size_t count, void *ptr) throw();Copy to clipboard

The first function is called by a
**`new[]` expression**
to allocate `count` bytes of storage
suitably aligned to represent any array object of
that size or smaller. The program can define a function
with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the Standard C++ library.

The required behavior is the same as for
`operator new(size_t)`.
The default behavior is to return
`operator new(count)`.

The second function is called by a
[placement
`new\[\]` expression](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#placement%20new[]%20expression)
to allocate `count` bytes of storage
suitably aligned to represent any array object of that size.
The program can define a function with this function signature that
[replaces](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#replaceable%20functions)
the default version defined by the Standard C++ library.

The default behavior is to return
`operator new(count)` if that
function succeeds. Otherwise, it returns a null pointer.

The third function is called by a
**placement`new[]` expression**,
of the form `new (args) T[N]`.
Here, `args` consists of a single object pointer.
The function returns `ptr`.

## `set_new_handler`

    new_handler set_new_handler(new_handler pnew) throw();Copy to clipboard

The function stores `pnew` in a static
[new handler](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_new.html#new%20handler) pointer
that it maintains, then returns the value previously
stored in the pointer. The new handler is used by
`operator new(size_t)`.

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<memory></memory> Next Topic

<new.h></new.h>