gen/posix_memalign.3

   1 .\" Copyright (c) 2006 Apple Computer, Inc.  All rights reserved.
   2 .\"
   3 .\" @APPLE_LICENSE_HEADER_START@
   4 .\"
   5 .\" The contents of this file constitute Original Code as defined in and
   6 .\" are subject to the Apple Public Source License Version 1.1 (the
   7 .\" "License").  You may not use this file except in compliance with the
   8 .\" License.  Please obtain a copy of the License at
   9 .\" http://www.apple.com/publicsource and read it before using this file.
  10 .\"
  11 .\" This Original Code and all software distributed under the License are
  12 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  13 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  14 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  16 .\" License for the specific language governing rights and limitations
  17 .\" under the License.
  18 .\"
  19 .\" @APPLE_LICENSE_HEADER_END@
  20 .\"
  21 .Dd April 9, 2008
  22 .Dt POSIX_MEMALIGN 3
  23 .Os
  24 .Sh NAME
  25 .Nm posix_memalign
  26 .Nd aligned memory allocation
  27 .Sh SYNOPSIS
  28 .In stdlib.h
  29 .Ft int
  30 .Fo posix_memalign
  31 .Fa "void **memptr"
  32 .Fa "size_t alignment"
  33 .Fa "size_t size"
  34 .Fc
  35 .Sh DESCRIPTION
  36 The
  37 .Fn posix_memalign
  38 function allocates
  39 .Fa size
  40 bytes of memory such that the allocation's base address is an exact multiple of
  41 .Fa alignment ,
  42 and returns the allocation in the value pointed to by
  43 .Fa memptr .
  44 .Pp
  45 The requested
  46 .Fa alignment
  47 must be a power of 2 at least as large as
  48 .Fn sizeof "void *" .
  49 .Pp
  50 Memory that is allocated via
  51 .Fn posix_memalign
  52 can be used as an argument in subsequent calls to
  53 .Xr realloc 3 ,
  54 .Xr reallocf 3 ,
  55 and
  56 .Xr free 3 .
  57 (Note however, that the allocation returned by
  58 .Xr realloc 3
  59 or
  60 .Xr reallocf 3
  61 is not guaranteed to preserve the original
  62 .Fa alignment ) .
  63 .Sh NOTES
  64 .Fn posix_memalign
  65 should be used judiciously as the algorithm that realizes the
  66 .Fa alignment
  67 constraint can incur significant memory overhead.
  68 .Sh RETURN VALUES
  69 The
  70 .Fn posix_memalign
  71 function returns the value 0 if successful; otherwise it returns an error value.
  72 .Sh ERRORS
  73 The
  74 .Fn posix_memalign
  75 function will fail if:
  76 .Bl -tag -width Er
  77 .It Bq Er EINVAL
  78 The
  79 .Fa alignment
  80 parameter is not a power of 2 at least as large as
  81 .Fn sizeof "void *" .
  82 .It Bq Er ENOMEM
  83 Memory allocation error.
  84 .El
  85 .Sh SEE ALSO
  86 .Xr free 3 ,
  87 .Xr malloc 3 ,
  88 .Xr realloc 3 ,
  89 .Xr reallocf 3 ,
  90 .Xr valloc 3 ,
  91 .Xr malloc_zone_memalign 3
  92 .Sh STANDARDS
  93 The
  94 .Fn posix_memalign
  95 function conforms to
  96 .St -p1003.1-2001 .