std::set_new_handler(3)

NAME
std::set_new_handler - std::set_new_handler

Synopsis
   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 his 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 (since C++11)
   std::set_new_handler and std::get_new_handler calls.

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
// Run this code
 #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
   operator new allocation functions
   operator new[] (function)
   get_new_handler obtains the current new handler
   (C++11) (function)
   new_handler function pointer type of the new handler
                   (typedef)
   bad_alloc exception thrown when memory allocation fails
                   (class)