man3/posix_memalign.3

   1 '\" t
   2 .\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk>
   3 .\" Based in part on GNU libc documentation.
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" 2001-10-11, 2003-08-22, aeb, added some details
   8 .\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com>
   9 .\"     Document pvalloc() and aligned_alloc()
  10 .TH posix_memalign 3 (date) "Linux man-pages (unreleased)"
  11 .SH NAME
  12 posix_memalign, aligned_alloc, memalign, valloc, pvalloc \-
  13 allocate aligned memory
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <stdlib.h>
  20 .P
  21 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
  22 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
  23 .BI "[[deprecated]] void *valloc(size_t " size );
  24 .P
  25 .B #include <malloc.h>
  26 .P
  27 .BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size );
  28 .BI "[[deprecated]] void *pvalloc(size_t " size );
  29 .fi
  30 .P
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .P
  36 .BR posix_memalign ():
  37 .nf
  38     _POSIX_C_SOURCE >= 200112L
  39 .fi
  40 .P
  41 .BR aligned_alloc ():
  42 .nf
  43     _ISOC11_SOURCE
  44 .fi
  45 .P
  46 .BR valloc ():
  47 .nf
  48     Since glibc 2.12:
  49         (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
  50             || /* glibc >= 2.19: */ _DEFAULT_SOURCE
  51             || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  52     Before glibc 2.12:
  53         _BSD_SOURCE || _XOPEN_SOURCE >= 500
  54 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  55 .fi
  56 .SH DESCRIPTION
  57 The function
  58 .BR posix_memalign ()
  59 allocates
  60 .I size
  61 bytes and places the address of the allocated memory in
  62 .IR "*memptr" .
  63 The address of the allocated memory will be a multiple of
  64 .IR "alignment" ,
  65 which must be a power of two and a multiple of
  66 .IR "sizeof(void\ *)" .
  67 This address can later be successfully passed to
  68 .BR free (3).
  69 If
  70 .I size
  71 is 0, then
  72 the value placed in
  73 .I *memptr
  74 is either NULL
  75 .\" glibc does this:
  76 or a unique pointer value.
  77 .P
  78 The obsolete function
  79 .BR memalign ()
  80 allocates
  81 .I size
  82 bytes and returns a pointer to the allocated memory.
  83 The memory address will be a multiple of
  84 .IR alignment ,
  85 which must be a power of two.
  86 .\" The behavior of memalign() for size==0 is as for posix_memalign()
  87 .\" but no standards govern this.
  88 .P
  89 The function
  90 .BR aligned_alloc ()
  91 is the same as
  92 .BR memalign (),
  93 except for the added restriction that
  94 .I alignment
  95 must be a power of two.
  96 .P
  97 The obsolete function
  98 .BR valloc ()
  99 allocates
 100 .I size
 101 bytes and returns a pointer to the allocated memory.
 102 The memory address will be a multiple of the page size.
 103 It is equivalent to
 104 .IR "memalign(sysconf(_SC_PAGESIZE),size)" .
 105 .P
 106 The obsolete function
 107 .BR pvalloc ()
 108 is similar to
 109 .BR valloc (),
 110 but rounds the size of the allocation up to
 111 the next multiple of the system page size.
 112 .P
 113 For all of these functions, the memory is not zeroed.
 114 .SH RETURN VALUE
 115 .BR aligned_alloc (),
 116 .BR memalign (),
 117 .BR valloc (),
 118 and
 119 .BR pvalloc ()
 120 return a pointer to the allocated memory on success.
 121 On error, NULL is returned, and \fIerrno\fP is set
 122 to indicate the error.
 123 .P
 124 .BR posix_memalign ()
 125 returns zero on success, or one of the error values listed in the
 126 next section on failure.
 127 The value of
 128 .I errno
 129 is not set.
 130 On Linux (and other systems),
 131 .BR posix_memalign ()
 132 does not modify
 133 .I memptr
 134 on failure.
 135 A requirement standardizing this behavior was added in POSIX.1-2008 TC2.
 136 .\" http://austingroupbugs.net/view.php?id=520
 137 .SH ERRORS
 138 .TP
 139 .B EINVAL
 140 The
 141 .I alignment
 142 argument was not a power of two, or was not a multiple of
 143 .IR "sizeof(void\ *)" .
 144 .TP
 145 .B ENOMEM
 146 There was insufficient memory to fulfill the allocation request.
 147 .SH ATTRIBUTES
 148 For an explanation of the terms used in this section, see
 149 .BR attributes (7).
 150 .TS
 151 allbox;
 152 lbx lb lb
 153 l l l.
 154 Interface       Attribute       Value
 155 T{
 156 .na
 157 .nh
 158 .BR aligned_alloc (),
 159 .BR memalign (),
 160 .BR posix_memalign ()
 161 T}      Thread safety   MT-Safe
 162 T{
 163 .na
 164 .nh
 165 .BR valloc (),
 166 .BR pvalloc ()
 167 T}      Thread safety   MT-Unsafe init
 168 .TE
 169 .SH STANDARDS
 170 .TP
 171 .BR aligned_alloc ()
 172 C11.
 173 .TP
 174 .BR posix_memalign ()
 175 POSIX.1-2008.
 176 .TP
 177 .BR memalign ()
 178 .TQ
 179 .BR valloc ()
 180 None.
 181 .TP
 182 .BR pvalloc ()
 183 GNU.
 184 .SH HISTORY
 185 .TP
 186 .BR aligned_alloc ()
 187 glibc 2.16.
 188 C11.
 189 .TP
 190 .BR posix_memalign ()
 191 glibc 2.1.91.
 192 POSIX.1d, POSIX.1-2001.
 193 .TP
 194 .BR memalign ()
 195 glibc 2.0.
 196 SunOS 4.1.3.
 197 .TP
 198 .BR valloc ()
 199 glibc 2.0.
 200 3.0BSD.
 201 Documented as obsolete in 4.3BSD,
 202 and as legacy in SUSv2.
 203 .TP
 204 .BR pvalloc ()
 205 glibc 2.0.
 206 .\"
 207 .SS Headers
 208 Everybody agrees that
 209 .BR posix_memalign ()
 210 is declared in \fI<stdlib.h>\fP.
 211 .P
 212 On some systems
 213 .BR memalign ()
 214 is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP.
 215 .P
 216 According to SUSv2,
 217 .BR valloc ()
 218 is declared in \fI<stdlib.h>\fP.
 219 .\" Libc4,5 and
 220 glibc declares it in \fI<malloc.h>\fP, and also in
 221 \fI<stdlib.h>\fP
 222 if suitable feature test macros are defined (see above).
 223 .SH NOTES
 224 On many systems there are alignment restrictions, for example, on buffers
 225 used for direct block device I/O.
 226 POSIX specifies the
 227 .I "pathconf(path,_PC_REC_XFER_ALIGN)"
 228 call that tells what alignment is needed.
 229 Now one can use
 230 .BR posix_memalign ()
 231 to satisfy this requirement.
 232 .P
 233 .BR posix_memalign ()
 234 verifies that
 235 .I alignment
 236 matches the requirements detailed above.
 237 .BR memalign ()
 238 may not check that the
 239 .I alignment
 240 argument is correct.
 241 .P
 242 POSIX requires that memory obtained from
 243 .BR posix_memalign ()
 244 can be freed using
 245 .BR free (3).
 246 Some systems provide no way to reclaim memory allocated with
 247 .BR memalign ()
 248 or
 249 .BR valloc ()
 250 (because one can pass to
 251 .BR free (3)
 252 only a pointer obtained from
 253 .BR malloc (3),
 254 while, for example,
 255 .BR memalign ()
 256 would call
 257 .BR malloc (3)
 258 and then align the obtained value).
 259 .\" Other systems allow passing the result of
 260 .\" .IR valloc ()
 261 .\" to
 262 .\" .IR free (3),
 263 .\" but not to
 264 .\" .IR realloc (3).
 265 The glibc implementation
 266 allows memory obtained from any of these functions to be
 267 reclaimed with
 268 .BR free (3).
 269 .P
 270 The glibc
 271 .BR malloc (3)
 272 always returns 8-byte aligned memory addresses, so these functions are
 273 needed only if you require larger alignment values.
 274 .SH SEE ALSO
 275 .BR brk (2),
 276 .BR getpagesize (2),
 277 .BR free (3),
 278 .BR malloc (3)