6 Basic concepts [basic]

6.7 Storage duration [basic.stc]

6.7.4 Dynamic storage duration [basic.stc.dynamic]

1
#
Objects can be created dynamically during program execution ([intro.execution]), using new-expressions, and destroyed using delete-expressions.
A C++ implementation provides access to, and management of, dynamic storage via the global allocation functions operator new and operator new[] and the global deallocation functions operator delete and operator delete[].
[ Note
:
The non-allocating forms described in [new.delete.placement] do not perform allocation or deallocation.
— end note
 ]
2
#
The library provides default definitions for the global allocation and deallocation functions.
Some global allocation and deallocation functions are replaceable ([new.delete]).
A C++ program shall provide at most one definition of a replaceable allocation or deallocation function.
Any such function definition replaces the default version provided in the library ([replacement.functions]).
The following allocation and deallocation functions ([support.dynamic]) are implicitly declared in global scope in each translation unit of a program.
void* operator new(std::size_t);
void* operator new(std::size_t, std::align_val_t);

void operator delete(void*) noexcept;
void operator delete(void*, std::size_t) noexcept;
void operator delete(void*, std::align_val_t) noexcept;
void operator delete(void*, std::size_t, std::align_val_t) noexcept;

void* operator new[](std::size_t);
void* operator new[](std::size_t, std::align_val_t);

void operator delete[](void*) noexcept;
void operator delete[](void*, std::size_t) noexcept;
void operator delete[](void*, std::align_val_t) noexcept;
void operator delete[](void*, std::size_t, std::align_val_t) noexcept;
These implicit declarations introduce only the function names operator new, operator new[], operator delete, and operator delete[].
[ Note
:
The implicit declarations do not introduce the names std, std​::​size_­t, std​::​align_­val_­t, or any other names that the library uses to declare these names.
Thus, a new-expression, delete-expression or function call that refers to one of these functions without including the header <new> is well-formed.
However, referring to std or std​::​size_­t or std​::​align_­val_­t is ill-formed unless the name has been declared by including the appropriate header.
— end note
 ]
Allocation and/or deallocation functions may also be declared and defined for any class ([class.free]).
3
#
Any allocation and/or deallocation functions defined in a C++ program, including the default versions in the library, shall conform to the semantics specified in [basic.stc.dynamic.allocation] and [basic.stc.dynamic.deallocation].

6.7.4.1 Allocation functions [basic.stc.dynamic.allocation]

1
#
An allocation function shall be a class member function or a global function; a program is ill-formed if an allocation function is declared in a namespace scope other than global scope or declared static in global scope.
The return type shall be void*.
The first parameter shall have type std​::​size_­t ([support.types]).
The first parameter shall not have an associated default argument ([dcl.fct.default]).
The value of the first parameter shall be interpreted as the requested size of the allocation.
An allocation function can be a function template.
Such a template shall declare its return type and first parameter as specified above (that is, template parameter types shall not be used in the return type and first parameter type).
Template allocation functions shall have two or more parameters.
2
#
The allocation function attempts to allocate the requested amount of storage.
If it is successful, it shall return the address of the start of a block of storage whose length in bytes shall be at least as large as the requested size.
There are no constraints on the contents of the allocated storage on return from the allocation function.
The order, contiguity, and initial value of storage allocated by successive calls to an allocation function are unspecified.
The pointer returned shall be suitably aligned so that it can be converted to a pointer to any suitable complete object type ([new.delete.single]) and then used to access the object or array in the storage allocated (until the storage is explicitly deallocated by a call to a corresponding deallocation function).
Even if the size of the space requested is zero, the request can fail.
If the request succeeds, the value returned shall be a non-null pointer value ([conv.ptr]) p0 different from any previously returned value p1, unless that value p1 was subsequently passed to an operator delete.
Furthermore, for the library allocation functions in [new.delete.single] and [new.delete.array], p0 shall represent the address of a block of storage disjoint from the storage for any other object accessible to the caller.
The effect of indirecting through a pointer returned as a request for zero size is undefined.38
3
#
An allocation function that fails to allocate storage can invoke the currently installed new-handler function ([new.handler]), if any.
[ Note
:
A program-supplied allocation function can obtain the address of the currently installed new_­handler using the std​::​get_­new_­handler function ([set.new.handler]).
— end note
 ]
If an allocation function that has a non-throwing exception specification ([except.spec]) fails to allocate storage, it shall return a null pointer.
Any other allocation function that fails to allocate storage shall indicate failure only by throwing an exception ([except.throw]) of a type that would match a handler ([except.handle]) of type std​::​bad_­alloc ([bad.alloc]).
4
#
A global allocation function is only called as the result of a new expression ([expr.new]), or called directly using the function call syntax ([expr.call]), or called indirectly through calls to the functions in the C++ standard library.
[ Note
:
In particular, a global allocation function is not called to allocate storage for objects with static storage duration ([basic.stc.static]), for objects or references with thread storage duration ([basic.stc.thread]), for objects of type std​::​type_­info ([expr.typeid]), or for an exception object ([except.throw]).
— end note
 ]
38)
The intent is to have operator new() implementable by calling std​::​malloc() or std​::​calloc(), so the rules are substantially the same.
C++ differs from C in requiring a zero request to return a non-null pointer.

6.7.4.2 Deallocation functions [basic.stc.dynamic.deallocation]

1
#
Deallocation functions shall be class member functions or global functions; a program is ill-formed if deallocation functions are declared in a namespace scope other than global scope or declared static in global scope.
2
#
Each deallocation function shall return void and its first parameter shall be void*.
A deallocation function may have more than one parameter.
A usual deallocation function is a deallocation function that has:
  • (2.1)
    exactly one parameter; or
  • (2.2)
    exactly two parameters, the type of the second being either std​::​align_­val_­t or std​::​size_­t39; or
  • (2.3)
    exactly three parameters, the type of the second being std​::​size_­t and the type of the third being std​::​align_­val_­t.
A deallocation function may be an instance of a function template.
Neither the first parameter nor the return type shall depend on a template parameter.
[ Note
:
That is, a deallocation function template shall have a first parameter of type void* and a return type of void (as specified above).
— end note
 ]
A deallocation function template shall have two or more function parameters.
A template instance is never a usual deallocation function, regardless of its signature.
3
#
If a deallocation function terminates by throwing an exception, the behavior is undefined.
The value of the first argument supplied to a deallocation function may be a null pointer value; if so, and if the deallocation function is one supplied in the standard library, the call has no effect.
4
#
If the argument given to a deallocation function in the standard library is a pointer that is not the null pointer value ([conv.ptr]), the deallocation function shall deallocate the storage referenced by the pointer, ending the duration of the region of storage.
39)
The global operator delete(void*, std​::​size_­t) precludes use of an allocation function void operator new(std​::​size_­t, std​::​size_­t) as a placement allocation function ([diff.cpp11.basic]).

6.7.4.3 Safely-derived pointers [basic.stc.dynamic.safety]

1
#
A traceable pointer object is
  • (1.1)
    an object of an object pointer type ([basic.compound]), or
  • (1.2)
    an object of an integral type that is at least as large as std​::​intptr_­t, or
  • (1.3)
    a sequence of elements in an array of narrow character type ([basic.fundamental]), where the size and alignment of the sequence match those of some object pointer type.
2
#
A pointer value is a safely-derived pointer to a dynamic object only if it has an object pointer type and it is one of the following:
  • (2.1)
    the value returned by a call to the C++ standard library implementation of ​::​operator new(std​::​​size_­t) or ​::​operator new(std​::​size_­t, std​::​align_­val_­t);40
  • (2.2)
    the result of taking the address of an object (or one of its subobjects) designated by an lvalue resulting from indirection through a safely-derived pointer value;
  • (2.3)
    the result of well-defined pointer arithmetic ([expr.add]) using a safely-derived pointer value;
  • (2.4)
    the result of a well-defined pointer conversion ([conv.ptr], [expr.cast]) of a safely-derived pointer value;
  • (2.5)
    the result of a reinterpret_­cast of a safely-derived pointer value;
  • (2.6)
    the result of a reinterpret_­cast of an integer representation of a safely-derived pointer value;
  • (2.7)
    the value of an object whose value was copied from a traceable pointer object, where at the time of the copy the source object contained a copy of a safely-derived pointer value.
3
#
An integer value is an integer representation of a safely-derived pointer only if its type is at least as large as std​::​intptr_­t and it is one of the following:
  • (3.1)
    the result of a reinterpret_­cast of a safely-derived pointer value;
  • (3.2)
    the result of a valid conversion of an integer representation of a safely-derived pointer value;
  • (3.3)
    the value of an object whose value was copied from a traceable pointer object, where at the time of the copy the source object contained an integer representation of a safely-derived pointer value;
  • (3.4)
    the result of an additive or bitwise operation, one of whose operands is an integer representation of a safely-derived pointer value P, if that result converted by reinterpret_­cast<void*> would compare equal to a safely-derived pointer computable from reinterpret_­cast<void*>(P).
4
#
An implementation may have relaxed pointer safety, in which case the validity of a pointer value does not depend on whether it is a safely-derived pointer value.
Alternatively, an implementation may have strict pointer safety, in which case a pointer value referring to an object with dynamic storage duration that is not a safely-derived pointer value is an invalid pointer value unless the referenced complete object has previously been declared reachable ([util.dynamic.safety]).
[ Note
:
The effect of using an invalid pointer value (including passing it to a deallocation function) is undefined, see [basic.stc.dynamic.deallocation].
This is true even if the unsafely-derived pointer value might compare equal to some safely-derived pointer value.
— end note
 ]
It is implementation-defined whether an implementation has relaxed or strict pointer safety.
40)
This section does not impose restrictions on indirection through pointers to memory not allocated by ​::​operator new.
This maintains the ability of many C++ implementations to use binary libraries and components written in other languages.
In particular, this applies to C binaries, because indirection through pointers to memory allocated by std​::​malloc is not restricted.