Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
std::aligned_alloc(3)	      C++ Standard Libary	 std::aligned_alloc(3)

NAME
       std::aligned_alloc - std::aligned_alloc

Synopsis
	  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. The size parameter	must be	an integral multiple of	align-
       ment.

	  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,
       (since C++11)
	      std::aligned_alloc
	      (since C++17), 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 sup-
       ported 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 func-
       tion to fail and
	  return a null	pointer	(C11, as published, specified undefined	behav-
       ior in this case,
	  this was corrected by	DR 460).

	  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  in-
       herit this
	  requirements.

	  Regular  std::malloc	aligns	memory	suitable  for  any object type
       (which, in practice,
	  means	that it	is aligned to alignof(std::max_align_t)).  This	 func-
       tion is useful for
	  over-aligned	allocations,  such  as	to SSE,	cache line, or VM page
       boundary.

Example
       // Run this code

	#include <cstdio>
	#include <cstdlib>

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

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

Possible output:
	default-aligned	address:   0x2221c20
	1024-byte aligned address: 0x2222400

See also
	  aligned_storage	       defines the type	suitable  for  use  as
       uninitialized
	  (C++11)(deprecated in	C++23) storage for types of given size
				       (class template)

http://cppreference.com		  2022.07.31		 std::aligned_alloc(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::aligned_alloc&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help