new(3C++std)

new_handler , bad_alloc , nothrow_t , nothrow , set_new_handler , operator delete , operator delete , operator delete , operator delete[] , operator delete[] , operator delete[] , operator new , operator new , operator new , operator new[] , operator new[] , operator new[] - declares several functions that allocate and free storage

Synopsis

   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 ph) throw();
       };

           // OPERATORS -- NOT IN NAMESPACE std
   void operator delete(void *p) throw();  // REPLACEABLE
   void operator delete(void *, void *) throw();
   void operator delete(void *p,  // REPLACEABLE
       const std::nothrow_t&) throw();
   void operator delete[](void *p) throw();  // REPLACEABLE
   void operator delete[](void *, void *) throw();
   void operator delete[](void *p,  // REPLACEABLE
       const std::nothrow_t&) throw();
   void *operator new(std::size_t n)  // REPLACEABLE
       throw(std::bad_alloc);
   void *operator new(std::size_t n,  // REPLACEABLE
       const std::nothrow_t&) throw();
   void *operator new(std::size_t n, void *p) throw();
   void *operator new[](std::size_t n)  // REPLACEABLE
       throw(std::bad_alloc);
   void *operator new[](std::size_t n,  // REPLACEABLE
       const std::nothrow_t&) throw();
   void *operator new[](std::size_t n, void *p) throw();

Description

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.

bad_alloc

   class bad_alloc : public exception {
       };

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. None of the member functions throw any exceptions.

new_handler

   typedef void (*new_handler)();

The type points to a function suitable for use as a new handler.

nothrow

   extern const nothrow_t nothrow;

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

nothrow_t

   class nothrow_t {};

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 *p) throw();  // REPLACEABLE
   void operator delete(void *, void *) throw();
   void operator delete(void *p,  // REPLACEABLE
       const std::nothrow_t&) throw();

The first function is called by a delete expression to render the value of p invalid. The program can define a function with this function signature that replaces the default version defined by the Standard C++ library. The required behavior is to accept a value of p that is null or that was returned by an earlier call to operator new(size_t).

The default behavior for a null value of p is to do nothing. Any other value of p must be a value returned earlier by a call as described above. The default behavior for such a non-null value of p 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 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 the default version defined by the Standard C++ library. The required behavior is to accept a value of p that is null or that was returned by an earlier call to operator new(size_t). The default behavior is to evaluate delete(p).

operator delete[]

   void operator delete[](void *p) throw();  // REPLACEABLE
   void operator delete[](void *, void *) throw();
   void operator delete[](void *p,  // REPLACEABLE
       const std::nothrow_t&) throw();

The first function is called by a delete[] expression to render the value of p invalid. The program can define a function with this function signature that replaces the default version defined by the Standard C++ library.

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

The default behavior for a null value of p 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 p 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 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 the default version defined by the Standard C++ library. The required behavior is to accept a value of p that is null or that was returned by an earlier call to operator new[](size_t). The default behavior is to evaluate delete[](p).

operator new

   void *operator new(std::size_t n) throw(bad_alloc);  // REPLACEABLE
   void *operator new(std::size_t n,  // REPLACEABLE
       const std::nothrow_t&) throw();
   void *operator new(std::size_t n, void *p) throw();

The first function is called by a new expression to allocate n bytes of storage suitably aligned to represent any object of that size. The program can define a function with this function signature that replaces 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 points to the start (lowest byte address) of the allocated storage. If n 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. 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

The default behavior of a new handler 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 n,
       const std::nothrow_t&) throw();

is called by a placement new expression to allocate n bytes of storage suitably aligned to represent any object of that size. The program can define a function with this function signature that replaces the default version defined by the Standard C++ library.

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

The third function:

   void *operator new(std::size_t n, void *p) throw();

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

operator new[]

   void *operator new[](std::size_t n)  // REPLACEABLE
       throw(std::bad_alloc);
   void *operator new[](std::size_t n,  // REPLACEABLE
       const std::nothrow_t&) throw();
   void *operator new[](std::size_t n, void *p) throw();

The first function is called by a new[] expression to allocate n 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 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(n).

The second function is called by a placement new[] expression to allocate n 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 the default version defined by the Standard C++ library.

The default behavior is to return operator new(n) 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 p.

set_new_handler

   new_handler set_new_handler(new_handler ph) throw();

The function stores ph in a static new handler pointer that it maintains, then returns the value previously stored in the pointer. The new handler is used by operator new(size_t).

References

exception(3C++std) , stdlib(5)