original/man3/posix_memalign.3

   1 .\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk>
   2 .\" Based in part on GNU libc documentation.
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" License.
  24 .\"
  25 .\" 2001-10-11, 2003-08-22, aeb, added some details
  26 .TH POSIX_MEMALIGN 3  2009-03-30 "GNU" "Linux Programmer's Manual"
  27 .SH NAME
  28 posix_memalign, memalign, valloc \- Allocate aligned memory
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <stdlib.h>
  32 .sp
  33 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
  34 .sp
  35 .B #include <malloc.h>
  36 .sp
  37 .BI "void *valloc(size_t " size );
  38 .BI "void *memalign(size_t " boundary ", size_t " size );
  39 .fi
  40 .sp
  41 .in -4n
  42 Feature Test Macro Requirements for glibc (see
  43 .BR feature_test_macros (7)):
  44 .in
  45 .sp
  46 .ad l
  47 .BR posix_memalign ():
  48 _POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
  49 .ad b
  50 .SH DESCRIPTION
  51 The function
  52 .BR posix_memalign ()
  53 allocates
  54 .I size
  55 bytes and places the address of the allocated memory in
  56 .IR "*memptr" .
  57 The address of the allocated memory will be a multiple of
  58 .IR "alignment" ,
  59 which must be a power of two and a multiple of
  60 .IR "sizeof(void *)".
  61 If
  62 .I size
  63 is 0, then
  64 .BR posix_memalign ()
  65 returns either NULL,
  66 .\" glibc does this:
  67 or a unique pointer value that can later be successfully passed to
  68 .BR free ().
  69
  70 The obsolete function
  71 .BR memalign ()
  72 allocates
  73 .I size
  74 bytes and returns a pointer to the allocated memory.
  75 The memory address will be a multiple of
  76 .IR "boundary" ,
  77 which must be a power of two.
  78 .\" The behavior of memalign() for size==0 is as for posix_memalign()
  79 .\" but no standards govern this.
  80
  81 The obsolete function
  82 .BR valloc ()
  83 allocates
  84 .I size
  85 bytes and returns a pointer to the allocated memory.
  86 The memory address will be a multiple of the page size.
  87 It is equivalent to
  88 .IR "memalign(sysconf(_SC_PAGESIZE),size)" .
  89
  90 For all three routines, the memory is not zeroed.
  91 .SH "RETURN VALUE"
  92 .BR memalign ()
  93 and
  94 .BR valloc ()
  95 return the pointer to the allocated memory, or NULL if the request fails.
  96
  97 .BR posix_memalign ()
  98 returns zero on success, or one of the error values listed in the
  99 next section on failure.
 100 Note that
 101 .I errno
 102 is not set.
 103 .SH "ERRORS"
 104 .TP
 105 .B EINVAL
 106 The
 107 .I alignment
 108 argument was not a power of two, or was not a multiple of
 109 .IR "sizeof(void *)" .
 110 .TP
 111 .B ENOMEM
 112 There was insufficient memory to fulfill the allocation request.
 113 .SH VERSIONS
 114 The functions
 115 .BR memalign ()
 116 and
 117 .BR valloc ()
 118 have been available in all Linux libc libraries.
 119 The function
 120 .BR posix_memalign ()
 121 is available since glibc 2.1.91.
 122 .SH "CONFORMING TO"
 123 The function
 124 .BR valloc ()
 125 appeared in 3.0BSD.
 126 It is documented as being obsolete in 4.3BSD,
 127 and as legacy in SUSv2.
 128 It does not appear in POSIX.1-2001.
 129 The function
 130 .BR memalign ()
 131 appears in SunOS 4.1.3 but not in 4.4BSD.
 132 The function
 133 .BR posix_memalign ()
 134 comes from POSIX.1d.
 135 .SS Headers
 136 Everybody agrees that
 137 .BR posix_memalign ()
 138 is declared in \fI<stdlib.h>\fP.
 139
 140 On some systems
 141 .BR memalign ()
 142 is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP.
 143
 144 According to SUSv2,
 145 .BR valloc ()
 146 is declared in \fI<stdlib.h>\fP.
 147 Libc4,5 and glibc declare it in \fI<malloc.h>\fP and perhaps also in
 148 \fI<stdlib.h>\fP
 149 (namely, if
 150 .B _GNU_SOURCE
 151 is defined, or
 152 .B _BSD_SOURCE
 153 is defined, or,
 154 for glibc, if
 155 .B _XOPEN_SOURCE_EXTENDED
 156 is defined, or, equivalently,
 157 .B _XOPEN_SOURCE
 158 is defined to a value not less than 500).
 159 .SH NOTES
 160 On many systems there are alignment restrictions, for example, on buffers
 161 used for direct block device I/O.
 162 POSIX specifies the
 163 .I "pathconf(path,_PC_REC_XFER_ALIGN)"
 164 call that tells what alignment is needed.
 165 Now one can use
 166 .BR posix_memalign ()
 167 to satisfy this requirement.
 168
 169 .BR posix_memalign ()
 170 verifies that
 171 .I alignment
 172 matches the requirements detailed above.
 173 .BR memalign ()
 174 may not check that the
 175 .I boundary
 176 argument is correct.
 177
 178 POSIX requires that memory obtained from
 179 .BR posix_memalign ()
 180 can be freed using
 181 .BR free (3).
 182 Some systems provide no way to reclaim memory allocated with
 183 .BR memalign ()
 184 or
 185 .BR valloc ()
 186 (because one can only pass to
 187 .BR free (3)
 188 a pointer gotten from
 189 .BR malloc (3),
 190 while, for example,
 191 .BR memalign ()
 192 would call
 193 .BR malloc (3)
 194 and then align the obtained value).
 195 .\" Other systems allow passing the result of
 196 .\" .IR valloc ()
 197 .\" to
 198 .\" .IR free (3),
 199 .\" but not to
 200 .\" .IR realloc (3).
 201 The glibc implementation
 202 allows memory obtained from any of these three routines to be
 203 reclaimed with
 204 .BR free (3).
 205
 206 The glibc
 207 .BR malloc (3)
 208 always returns 8-byte aligned memory addresses, so these routines are only
 209 needed if you require larger alignment values.
 210 .SH "SEE ALSO"
 211 .BR brk (2),
 212 .BR getpagesize (2),
 213 .BR free (3),
 214 .BR malloc (3)