Skip to content

Search topics & cppreference

Search all study topics, concept maps, and 6,587 C++ and C reference pages.

std::set_new_handler

Makes new_p the new global new-handler function and returns the previously installed new-handler.

NotebookLM
Defined in header <new>
std::new_handler set_new_handler( std::new_handler new_p ) throw();
(until C++11)
std::new_handler set_new_handler( std::new_handler new_p ) noexcept;
(since C++11)

Makes new_p the new global new-handler function and returns the previously installed new-handler.

The new-handler function is the function called by allocation functions whenever a memory allocation attempt fails. Its intended purpose is one of three things:

1) make more memory available,
2) terminate the program (e.g. by calling std::terminate),
3) throw exception of type std::bad_alloc or derived from std::bad_alloc.

The default implementation throws std::bad_alloc. The user can install their own new-handler, which may offer behavior different than the default one.

If new-handler returns, the allocation function repeats the previously-failed allocation attempt and calls the new-handler again if the allocation fails again. To end the loop, new-handler may call std::set_new_handler(nullptr): if, after a failed allocation attempt, allocation function finds that std::get_new_handler returns a null pointer value, it will throw std::bad_alloc.

At program startup, new-handler is a null pointer.

This function is thread-safe. Every call to std::set_new_handler synchronizes-with (see std::memory_order) the subsequent std::set_new_handler and std::get_new_handler calls.

(since C++11)

Parameters

new_p - pointer to function of type std::new_handler, or null pointer

Return value

The previously-installed new handler, or a null pointer value if none was installed.

Example

example.cpp
#include <iostream>
#include <new>
 
void handler()
{
    std::cout << "Memory allocation failed, terminating\n";
    std::set_new_handler(nullptr);
}
 
int main()
{
    std::set_new_handler(handler);
    try
    {
        while (true)
        {
            new int[1000'000'000ul]();
        }
    }
    catch (const std::bad_alloc& e)
    {
        std::cout << e.what() << '\n';
    }
}
Possible output
Memory allocation failed, terminating
std::bad_alloc

See also

allocation functions
(function)
obtains the current new handler
(function)
function pointer type of the new handler
(typedef)
exception thrown when memory allocation fails
(class)

Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.