[basic.stc.dynamic.allocation]

# 6 Basics [[basic]](./#basic)

## 6.8 Memory and objects [[basic.memobj]](basic.memobj#basic.stc.dynamic.allocation)

### 6.8.6 Storage duration [[basic.stc]](basic.stc#dynamic.allocation)

#### 6.8.6.5 Dynamic storage duration [[basic.stc.dynamic]](basic.stc.dynamic#allocation)

#### 6.8.6.5.2 Allocation functions [basic.stc.dynamic.allocation]

[1](#1)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/basic.tex#L4444)

An allocation function that is not a class member function
shall belong to the global scope and not have a name with internal linkage[.](#1.sentence-1)

The return type shall be void*[.](#1.sentence-2)

The first
parameter shall have type std​::​size_t ([[support.types]](support.types "17.2 Common definitions"))[.](#1.sentence-3)

The
first parameter shall not have an associated default
argument ([[dcl.fct.default]](dcl.fct.default "9.3.4.7 Default arguments"))[.](#1.sentence-4)

The value of the first parameter
is interpreted as the requested size of the allocation[.](#1.sentence-5)

An allocation
function can be a function template[.](#1.sentence-6)

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)[.](#1.sentence-7)

Allocation function templates shall have two or more parameters[.](#1.sentence-8)

[2](#2)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/basic.tex#L4458)

An allocation function attempts to allocate the requested amount of
storage[.](#2.sentence-1)

If it is successful, it returns the address of the start
of a block of storage whose length in bytes is at least as large
as the requested size[.](#2.sentence-2)

The order,
contiguity, and initial value of storage allocated by successive calls
to an allocation function are unspecified[.](#2.sentence-3)

Even if the size of the space
requested is zero, the request can fail[.](#2.sentence-4)

If the request succeeds, the
value returned by a replaceable allocation function
is a non-null pointer value ([[basic.compound]](basic.compound "6.9.4 Compound types"))p0 different from any previously returned value p1,
unless that value p1 was subsequently passed to a
replaceable deallocation function[.](#2.sentence-5)

Furthermore, for the library allocation functions
in [[new.delete.single]](new.delete.single "17.6.3.2 Single-object forms") and [[new.delete.array]](new.delete.array "17.6.3.3 Array forms"),p0 represents the address of a block of storage disjoint from the storage
for any other object accessible to the caller[.](#2.sentence-6)

The effect of indirecting through a pointer
returned from a request for zero size is undefined[.](#2.sentence-7)[23](#footnote-23 "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.")

[3](#3)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/basic.tex#L4487)

For an allocation function other than
a reserved placement allocation function ([[new.delete.placement]](new.delete.placement "17.6.3.4 Non-allocating forms")),
the pointer returned on a successful call
shall represent the address of storage that is aligned as follows:

- [(3.1)](#3.1)

  If the allocation function takes an argument
 of type std​::​align_val_t,
 the storage will have the alignment specified
 by the value of this argument[.](#3.1.sentence-1)

- [(3.2)](#3.2)

  Otherwise, if the allocation function is named operator new[],
 the storage is aligned for any object that
 does not have new-extended alignment ([[basic.align]](basic.align "6.8.3 Alignment")) and
 is no larger than the requested size[.](#3.2.sentence-1)

- [(3.3)](#3.3)

  Otherwise, the storage is aligned for any object that
 does not have new-extended alignment and is of the requested size[.](#3.3.sentence-1)

[4](#4)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/basic.tex#L4508)

An allocation function that fails to allocate storage can invoke the
currently installed new-handler function ([[new.handler]](new.handler "17.6.4.3 Type new_­handler")), if any[.](#4.sentence-1)

[*Note [1](#note-1)*:

A program-supplied allocation function can obtain the
currently installed new_handler using thestd​::​get_new_handler function ([[get.new.handler]](get.new.handler "17.6.4.5 get_­new_­handler"))[.](#4.sentence-2)

â *end note*]

An allocation function that has a non-throwing
exception specification ([[except.spec]](except.spec "14.5 Exception specifications"))
indicates failure by returning
a null pointer value[.](#4.sentence-3)

Any other allocation function
never returns a null pointer value and
indicates failure only by throwing an exception ([[except.throw]](except.throw "14.2 Throwing an exception")) of a type
that would match a handler ([[except.handle]](except.handle "14.4 Handling an exception")) of typestd​::​bad_alloc ([[bad.alloc]](bad.alloc "17.6.4.1 Class bad_­alloc"))[.](#4.sentence-4)

[5](#5)

[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/basic.tex#L4527)

A global allocation function is only called as the result of a [new
expression](expr.new "7.6.2.8 New [expr.new]"), or called directly using the [function call](expr.call "7.6.1.3 Function call [expr.call]") syntax, or called indirectly to allocate storage for
a coroutine state ([[dcl.fct.def.coroutine]](dcl.fct.def.coroutine "9.6.4 Coroutine definitions")),
or called indirectly through calls to the
functions in the C++ standard library[.](#5.sentence-1)

[*Note [2](#note-2)*:

In particular, a
global allocation function is not called to allocate storage
for objects with static storage duration ([[basic.stc.static]](basic.stc.static "6.8.6.2 Static storage duration")),
for objects or references with thread storage duration ([[basic.stc.thread]](basic.stc.thread "6.8.6.3 Thread storage duration")),
for objects of type std​::​type_info ([[expr.typeid]](expr.typeid "7.6.1.8 Type identification")),
for an object of type std​::​contracts​::​contract_violation when a contract violation occurs ([[basic.contract.eval]](basic.contract.eval "6.11.2 Evaluation")), or
for an exception object ([[except.throw]](except.throw "14.2 Throwing an exception"))[.](#5.sentence-2)

â *end note*]

[23)](#footnote-23)[23)](#footnoteref-23)

The intent is
to have operator new() implementable by
calling std​::​malloc() or std​::​calloc(), so the rules are
substantially the same[.](#footnote-23.sentence-1)

C++ differs from C in requiring a zero request
to return a non-null pointer[.](#footnote-23.sentence-2)
