_aligned_malloc

Allocates memory on a specified alignment boundary.

Syntax

void * _aligned_malloc(
    size_t size,
    size_t alignment
);

Parameters

size
Size of the requested memory allocation.

alignment
The alignment value, which must be an integer power of 2.

Return value

A pointer to the memory block that was allocated or NULL if the operation failed. The pointer is a multiple of alignment.

Remarks

_aligned_malloc is based on malloc.

_aligned_malloc is marked __declspec(noalias) and __declspec(restrict), meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see noalias and restrict.

This function sets errno to ENOMEM if the memory allocation failed or if the requested size was greater than _HEAP_MAXREQ. For more information about errno, see errno, _doserrno, _sys_errlist, and _sys_nerr. Also, _aligned_malloc validates its parameters. If alignment isn't a power of 2 or size is zero, this function invokes the invalid parameter handler, as described in Parameter validation. If execution is allowed to continue, this function returns NULL and sets errno to EINVAL.

Use _aligned_free to deallocate memory obtained by both _aligned_malloc and _aligned_offset_malloc. Don't use free, which doesn't reclaim the aligned memory correctly and can lead to hard-to-diagnose bugs.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Requirements

Example

// crt_aligned_malloc.c

#include <malloc.h>
#include <stdio.h>

int main() {
    void    *ptr;
    size_t  alignment,
            off_set;

    // Note alignment should be 2^N where N is any positive int.
    alignment = 16;
    off_set = 5;

    // Using _aligned_malloc
    ptr = _aligned_malloc(100, alignment);
    if (ptr == NULL)
    {
        printf_s( "Error allocation aligned memory.");
        return -1;
    }
    if (((unsigned long long)ptr % alignment ) == 0)
        printf_s( "This pointer, %p, is aligned on %zu\n",
                  ptr, alignment);
    else
        printf_s( "This pointer, %p, is not aligned on %zu\n",
                  ptr, alignment);

    // Using _aligned_realloc
    ptr = _aligned_realloc(ptr, 200, alignment);
    if ( ((unsigned long long)ptr % alignment ) == 0)
        printf_s( "This pointer, %p, is aligned on %zu\n",
                  ptr, alignment);
    else
        printf_s( "This pointer, %p, is not aligned on %zu\n",
                  ptr, alignment);
    _aligned_free(ptr);

    // Using _aligned_offset_malloc
    ptr = _aligned_offset_malloc(200, alignment, off_set);
    if (ptr == NULL)
    {
        printf_s( "Error allocation aligned offset memory.");
        return -1;
    }
    if ( ( (((unsigned long long)ptr) + off_set) % alignment ) == 0)
        printf_s( "This pointer, %p, is offset by %zu on alignment of %zu\n",
                  ptr, off_set, alignment);
    else
        printf_s( "This pointer, %p, does not satisfy offset %zu "
                  "and alignment %zu\n",ptr, off_set, alignment);

    // Using _aligned_offset_realloc
    ptr = _aligned_offset_realloc(ptr, 200, alignment, off_set);
    if (ptr == NULL)
    {
        printf_s( "Error reallocation aligned offset memory.");
        return -1;
    }
    if ( ( (((unsigned long long)ptr) + off_set) % alignment ) == 0)
        printf_s( "This pointer, %p, is offset by %zu on alignment of %zu\n",
                  ptr, off_set, alignment);
    else
        printf_s( "This pointer, %p, does not satisfy offset %zu and "
                  "alignment %zu\n", ptr, off_set, alignment);

    // Note that _aligned_free works for both _aligned_malloc
    // and _aligned_offset_malloc. Using free is illegal.
    _aligned_free(ptr);
}

This pointer, 3280880, is aligned on 16
This pointer, 3280880, is aligned on 16
This pointer, 3280891, is offset by 5 on alignment of 16
This pointer, 3280891, is offset by 5 on alignment of 16

See also

Data alignment