# std::aligned_alloc

> C++ Atlas: `cppatlas.com/w/cpp/memory/c/aligned_alloc` | Source: https://en.cppreference.com/w/cpp/memory/c/aligned_alloc | Domain: Memory management | Standards: C++11, C++17, C++23

Allocate size bytes of uninitialized storage whose alignment is specified by alignment (implicitly creating objects in the destination area).

## Official Specification Summary (cppreference)

```cpp
// Defined in header <cstdlib>
void* aligned_alloc( std::size_t alignment, std::size_t size ); // (since C++17)
```

Allocate `size` bytes of uninitialized storage whose alignment is specified by `alignment` (implicitly creating objects in the destination area). The `size` parameter must be an integral multiple of `alignment`.

The following functions are required to be thread-safe:

- The library versions of `operator new` and `operator delete`
- User replacement versions of global `operator new` and `operator delete`
- `std::calloc`, `std::malloc`, `std::realloc`, `std::aligned_alloc`, `std::free`

Calls to these functions that allocate or deallocate a particular unit of storage occur in a single total order, and each such deallocation call happens-before the next allocation (if any) in this order.

### Parameters

- `alignment` - specifies the alignment. Must be a valid alignment supported by the implementation.
- `size` - number of bytes to allocate. An integral multiple of `alignment`.

### Return value

On success, returns the pointer to the beginning of newly allocated memory. To avoid a memory leak, the returned pointer must be deallocated with `std::free` or `std::realloc`.

On failure, returns a null pointer.

### Notes

Passing a `size` which is not an integral multiple of `alignment` or an `alignment` which is not valid or not supported by the implementation causes the function to fail and return a null pointer (C11, as published, specified undefined behavior in this case, this was corrected by DR460).

As an example of the "supported by the implementation" requirement, POSIX function `posix_memalign` accepts any `alignment` that is a power of two and a multiple of `sizeof(void*)`, and POSIX-based implementations of `aligned_alloc` inherit this requirements.

Fundamental alignments are always supported. If `alignment` is a power of two and not greater than `alignof(std::max_align_t)`, `aligned_alloc` may simply call `std::malloc`.

Regular `std::malloc` aligns memory suitable for any object type with a fundamental alignment. This function is useful for over-aligned allocations, such as to SSE, cache line, or VM page boundary.

This function is not supported in Microsoft C Runtime library because its implementation of `std::free` is unable to handle aligned allocations of any kind. Instead, MS CRT provides `_aligned_malloc` (to be freed with `_aligned_free`).

### Example

```cpp
#include <cstdio>
#include <cstdlib>

int main()
{
    int* p1 = static_cast<int*>(std::malloc(10 * sizeof *p1));
    std::printf("default-aligned address:   %p\n", static_cast<void*>(p1));
    std::free(p1);

    int* p2 = static_cast<int*>(std::aligned_alloc(1024, 1024));
    std::printf("1024-byte aligned address: %p\n", static_cast<void*>(p2));
    std::free(p2);
}
```

Possible output:

```text
default-aligned address:   0x2221c20
1024-byte aligned address: 0x2222400
```

### See also

- [`aligned_storage`](https://en.cppreference.com/w/cpp/types/aligned_storage) (since C++11): defines the type suitable for use as uninitialized storage for types of given size (class template)
- [C documentation for `aligned_alloc`](https://en.cppreference.com/w/c/memory/aligned_alloc)

---
Attribution: content from https://en.cppreference.com/w/cpp/memory/c/aligned_alloc (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.