1.\" $NetBSD: posix_memalign.3,v 1.8 2025/01/11 11:41:08 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 July 27, 2018 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. 69.Pp 70Memory that is allocated via 71.Fn posix_memalign 72or 73.Fn aligned_alloc 74can be used as an argument in subsequent calls to 75.Xr realloc 3 76and 77.Xr free 3 . 78.Sh RETURN VALUES 79The 80.Fn posix_memalign 81function returns the value 0 if successful; otherwise it returns an error value. 82.Pp 83The 84.Fn aligned_alloc 85function returns a pointer to the allocated memory if successful; on failure it 86returns 87.Dv NULL 88and sets 89.Fa errno 90to indicate the error. 91.Sh ERRORS 92The 93.Fn posix_memalign 94and 95.Fn aligned_alloc 96functions will fail if: 97.Bl -tag -width Er 98.It Bq Er EINVAL 99The 100.Fa alignment 101parameter is not a power of 2. 102.It Bq Er ENOMEM 103Memory allocation error. 104.El 105.Pp 106The 107.Fn posix_memalign 108function will also fail if 109.Bl -tag -width Er 110.It Bq Er EINVAL 111The 112.Fa alignment 113parameter is not at least as large as 114.Fn sizeof "void *" . 115.El 116.Sh SEE ALSO 117.Xr free 3 , 118.Xr malloc 3 , 119.Xr realloc 3 , 120.Xr valloc 3 121.Sh STANDARDS 122The 123.Fn posix_memalign 124function conforms to 125.St -p1003.1-2001 . 126The 127.Fn aligned_alloc 128function conforms to 129.St -isoC-2011 . 130.Sh HISTORY 131.St -isoC-2011 132required size to be an integer multiple of alignment. 133This requirement was removed in later standards. 134