_aligned_malloc

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _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 is not 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 is not 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.

Requirements

Routine	Required header
`_aligned_malloc`	<malloc.h>

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

Share via