new(3C++)


new -- dynamic memory management

Synopsis

   #include <new> 
   

namespace std { class bad_alloc; struct nothrow_t {}; extern const nothrow_t nothrow; typedef void (*new_handler)(); new_handler set_new_handler(new_handler new_p) throw(); } void* operator new(std::size_t size) throw(std::bad_alloc); void* operator new(std::size_t size, const std::nothrow_t&) throw(); void operator delete(void* ptr) throw(); void operator delete(void* ptr, const std::nothrow_t&) throw(); void* operator new[](std::size_t size) throw(std::bad_alloc); void* operator new[](std::size_t size, const std::nothrow_t&) throw(); void operator delete[](void* ptr) throw(); void operator delete[](void* ptr, const std::nothrow_t&) throw(); void* operator new (std::size_t size, void* ptr) throw(); void* operator new[](std::size_t size, void* ptr) throw(); void operator delete (void* ptr, void*) throw(); void operator delete[](void* ptr, void*) throw();

Description

The header new defines several functions that manage the allocation of dynamic storage in a program. It also defines components for reporting storage management errors.

Functions

void* operator new(std::size_t size) throw(bad_alloc);
Effects: The allocation function called by a new-expression to allocate size bytes of storage suitably aligned to represent any object of that size.
Replaceable: A C++ program may define a function with this function signature that displaces the default version defined by the C++ Standard library.
Required behavior: Return a pointer to dynamically allocated storage, or else throw a bad_alloc exception.
Default behavior:

void* operator new(std::size_t size, const std::nothrow_t&) throw();
Effects: Same as above, except that it is called by a placement version of a new-expression when a C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.
Replaceable: a C++ program may define a function with this function signature that displaces the default version defined by the C++ Standard library.
Required behavior: Return a pointer to dynamically allocated storage, or else return a null pointer. This nothrow version of operator new returns a pointer obtained as if acquired from the ordinary version. This requirement is binding on a replacement version of this function.
Default behavior:

void operator delete(void* ptr) throw();

void operator delete(void* ptr, const std::nothrow_t&) throw();
Effects: The deallocation function called by a delete-expression to render the value of ptr invalid.
Replaceable: A C++ program may define a function with this function signature that displaces the default version defined by the C++ Standard library.
Required behavior: Accept a value of ptr that is null or that was returned by an earlier call to the default operator new(std::size_t) or operator new(std::size_t,const std::nothrow_t&).
Default behavior: Notes: It is unspecified under what conditions part or all of such reclaimed storage is allocated by a subsequent call to operatornew or any of malloc(3C) calloc(3C) or realloc(3C).

void* operator new[](std::size_t size) throw(bad_alloc);
Effects: The allocation function called by the array form of a new-expression to allocate size bytes of storage suitably aligned to represent any array object of that size or smaller.
Replaceable: A C++ program can define a function with this function signature that displaces the default version defined by the C++ Standard library.
Required behavior: Same as for operator new(std::size_t). This nothrow version of operator new[] returns a pointer obtained as if acquired from the ordinary version. This requirement is binding on a replacement ver- sion of this function.
Default behavior: Returns operator new(size).

void* operator new[](std::size_t size, const std::nothrow_t&) throw();
Effects: Same as above, except that it is called by a placement version of a new-expression when a C++ program prefers a null pointer result as an error indication, instead of a bad_alloc exception.
Replaceable: A C++ program can define a function with this function signature that displaces the default version defined by the C++ Standard library.
Required behavior: Same as for operator new(std::size_t,const std::nothrow_t&).
Default behavior: Returns operator new(size,nothrow).

void operator delete[](void* ptr) throw();

void operator delete[](void* ptr, const std::nothrow_t&) throw();
Effects: The deallocation function called by the array form of a delete-expression to render the value of ptr invalid.
Replaceable: A C++ program can define a function with this function signature that displaces the default version defined by the C++ Standard library.
Required behavior: Accept a value of ptr that is null or that was returned by an earlier call to operator new[](std::size_t) or operator new[](std::size_t,const std::nothrow_t&).
Default behavior: It is unspecified under what conditions part or all of such reclaimed storage is allocated by a subsequent call to operator new or any of malloc(3C) calloc(3C)or realloc(3C).

void* operator new(std::size_t size, void* ptr) throw();
Returns: ptr.
Replaceable: No.
Notes: Intentionally performs no other action.
Example: This can be useful for constructing an object at a known address:
   char place[sizeof(Something)]; 
   Something* p = new (place) Something(); 

void* operator new[](std::size_t size, void* ptr) throw();
Returns: ptr.
Replaceable: No.
Notes: Intentionally performs no other action.

void operator delete(void* ptr, void*) throw();
Effects: Intentionally performs no action.
Replaceable: No.
Notes: Default function called for a placement delete expression. Complements default placement new.

void operator delete[](void* ptr, void*) throw();
Effects: Intentionally performs no action.
Replaceable: No.
Notes: Default function called for a placement array delete expression. Complements default placement new[].

typedef void (*new_handler)();
The type of a handler function to be called by operator new() or operator new[]() when they cannot satisfy a request for additional storage.
Required behavior:A new_handler shall perform one of the following: Default behavior: The implementation's default new_handler throws an exception of type bad_alloc.

new_handler set_new_handler(new_handler new_p) throw();
Effects: Establishes the function designated by new_p as the current new_handler.
Returns: The previous new_handler.

Classes

   namespace std { 
     class bad_alloc : public exception { 
     public: 
       bad_alloc() throw(); 
       bad_alloc(const bad_alloc&) throw(); 
       bad_alloc& operator=(const bad_alloc&) throw(); 
       virtual ~bad_alloc() throw(); 
       virtual const char* what() const throw(); 
     }; 
   } 
The class bad_alloc defines the type of objects thrown as exceptions by the implementation to report a failure to allocate storage.

bad_alloc() throw();
Effects: Constructs an object of class bad_alloc.

bad_alloc(const bad_alloc&) throw();

bad_alloc& operator=(const bad_alloc&) throw();
Effects: Copies an object of class bad_alloc.

virtual const char* what() const throw();
Returns: The string std::bad_alloc.

References

malloc(3C)
30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.