1.\" $NetBSD: posix_memalign.3,v 1.3 2015/11/07 18:47:26 wiz Exp $ 2.\" 3.\" Copyright (C) 2006 Jason Evans <jasone@FreeBSD.org>. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice(s), this list of conditions and the following disclaimer as 11.\" the first lines of this file unmodified other than the possible 12.\" addition of one or more copyright notices. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice(s), this list of conditions and the following disclaimer in 15.\" the documentation and/or other materials provided with the 16.\" distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 19.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 25.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 26.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 27.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 28.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" FreeBSD: src/lib/libc/stdlib/posix_memalign.3,v 1.3 2007/03/28 04:32:51 jasone Exp 31.\" 32.Dd October 30, 2015 33.Dt POSIX_MEMALIGN 3 34.Os 35.Sh NAME 36.Nm posix_memalign , aligned_alloc 37.Nd aligned memory allocation 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In stdlib.h 42.Ft int 43.Fn posix_memalign "void **ptr" "size_t alignment" "size_t size" 44.Ft void * 45.Fn aligned_alloc "size_t alignment" "size_t size" 46.Sh DESCRIPTION 47The 48.Fn posix_memalign 49function allocates 50.Fa size 51bytes of memory such that the allocation's base address is an even multiple of 52.Fa alignment , 53and returns the allocation in the value pointed to by 54.Fa ptr . 55The requested 56.Fa alignment 57must be a power of 2 at least as large as 58.Fn sizeof "void *" . 59.Pp 60The 61.Fn aligned_alloc 62function allocates 63.Fa size 64bytes of memory such that the allocation's base address is an even multiple of 65.Fa alignment . 66The requested 67.Fa alignment 68must be a power of 2 and 69.Fa size 70must be a integer multiple of 71.Fa alignment . 72.Pp 73Memory that is allocated via 74.Fn posix_memalign 75or 76.Fn aligned_alloc 77can be used as an argument in subsequent calls to 78.Xr realloc 3 79and 80.Xr free 3 . 81.Sh RETURN VALUES 82The 83.Fn posix_memalign 84function returns the value 0 if successful; otherwise it returns an error value. 85.Pp 86The 87.Fn aligned_alloc 88function returns a pointer to the allocated memory if successful; on failure it 89returns 90.Dv NULL 91and sets 92.Fa errno 93to indicate the error. 94.Sh ERRORS 95The 96.Fn posix_memalign 97and 98.Fn aligned_alloc 99functions will fail if: 100.Bl -tag -width Er 101.It Bq Er EINVAL 102The 103.Fa alignment 104parameter is not a power of 2. 105.It Bq Er ENOMEM 106Memory allocation error. 107.El 108.Pp 109The 110.Fn posix_memalign 111function will also fail if 112.Bl -tag -width Er 113.It Bq Er EINVAL 114The 115.Fa alignment 116parameter is not at least as large as 117.Fn sizeof "void *" . 118.El 119.Pp 120The 121.Fn aligned_alloc 122function will also fail if 123.Bl -tag -width Er 124.It Bq Er EINVAL 125The 126.Fa size 127parameter is not an integer multiple of 128.Fa alignment . 129.El 130.Sh SEE ALSO 131.Xr free 3 , 132.Xr malloc 3 , 133.Xr realloc 3 , 134.Xr valloc 3 135.Sh STANDARDS 136The 137.Fn posix_memalign 138function conforms to 139.St -p1003.1-2001 . 140The 141.Fn aligned_alloc 142function conforms to 143.St -isoC-2011 . 144