lib/libc/posix_memalign.3

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