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 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" 2001-10-11, 2003-08-22, aeb, added some details
   7 .\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com>
   8 .\"     Document pvalloc() and aligned_alloc()
   9 .TH POSIX_MEMALIGN 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 posix_memalign, aligned_alloc, memalign, valloc, pvalloc \-
  12 allocate aligned memory
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <stdlib.h>
  19 .PP
  20 .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size );
  21 .BI "void *aligned_alloc(size_t " alignment ", size_t " size );
  22 .BI "void *valloc(size_t " size );
  23 .PP
  24 .B #include <malloc.h>
  25 .PP
  26 .BI "void *memalign(size_t " alignment ", size_t " size );
  27 .BI "void *pvalloc(size_t " size );
  28 .fi
  29 .PP
  30 .RS -4
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .RE
  34 .PP
  35 .BR posix_memalign ():
  36 .nf
  37     _POSIX_C_SOURCE >= 200112L
  38 .fi
  39 .PP
  40 .BR aligned_alloc ():
  41 .nf
  42     _ISOC11_SOURCE
  43 .fi
  44 .PP
  45 .BR valloc ():
  46 .nf
  47     Since glibc 2.12:
  48         (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L)
  49             || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  50             || /* Glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE
  51     Before glibc 2.12:
  52         _BSD_SOURCE || _XOPEN_SOURCE >= 500
  53 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  54 .fi
  55 .SH DESCRIPTION
  56 The function
  57 .BR posix_memalign ()
  58 allocates
  59 .I size
  60 bytes and places the address of the allocated memory in
  61 .IR "*memptr" .
  62 The address of the allocated memory will be a multiple of
  63 .IR "alignment" ,
  64 which must be a power of two and a multiple of
  65 .IR "sizeof(void\ *)" .
  66 This address can later be successfully passed to
  67 .BR free (3).
  68 If
  69 .I size
  70 is 0, then
  71 the value placed in
  72 .I *memptr
  73 is either NULL
  74 .\" glibc does this:
  75 or a unique pointer value.
  76 .PP
  77 The obsolete function
  78 .BR memalign ()
  79 allocates
  80 .I size
  81 bytes and returns a pointer to the allocated memory.
  82 The memory address will be a multiple of
  83 .IR alignment ,
  84 which must be a power of two.
  85 .\" The behavior of memalign() for size==0 is as for posix_memalign()
  86 .\" but no standards govern this.
  87 .PP
  88 The function
  89 .BR aligned_alloc ()
  90 is the same as
  91 .BR memalign (),
  92 except for the added restriction that
  93 .I size
  94 should be a multiple of
  95 .IR alignment .
  96 .PP
  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 .PP
 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 .PP
 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 .PP
 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 VERSIONS
 148 The functions
 149 .BR memalign (),
 150 .BR valloc (),
 151 and
 152 .BR pvalloc ()
 153 have been available since at least glibc 2.0.
 154 .PP
 155 The function
 156 .BR aligned_alloc ()
 157 was added to glibc in version 2.16.
 158 .PP
 159 The function
 160 .BR posix_memalign ()
 161 is available since glibc 2.1.91.
 162 .SH ATTRIBUTES
 163 For an explanation of the terms used in this section, see
 164 .BR attributes (7).
 165 .ad l
 166 .nh
 167 .TS
 168 allbox;
 169 lbx lb lb
 170 l l l.
 171 Interface       Attribute       Value
 172 T{
 173 .BR aligned_alloc (),
 174 .BR memalign (),
 175 .BR posix_memalign ()
 176 T}      Thread safety   MT-Safe
 177 T{
 178 .BR valloc (),
 179 .BR pvalloc ()
 180 T}      Thread safety   MT-Unsafe init
 181 .TE
 182 .hy
 183 .ad
 184 .sp 1
 185 .SH STANDARDS
 186 The function
 187 .BR valloc ()
 188 appeared in 3.0BSD.
 189 It is documented as being obsolete in 4.3BSD,
 190 and as legacy in SUSv2.
 191 It does not appear in POSIX.1.
 192 .PP
 193 The function
 194 .BR pvalloc ()
 195 is a GNU extension.
 196 .PP
 197 The function
 198 .BR memalign ()
 199 appears in SunOS 4.1.3 but not in 4.4BSD.
 200 .PP
 201 The function
 202 .BR posix_memalign ()
 203 comes from POSIX.1d and is specified in POSIX.1-2001 and POSIX.1-2008.
 204 .PP
 205 The function
 206 .BR aligned_alloc ()
 207 is specified in the C11 standard.
 208 .\"
 209 .SS Headers
 210 Everybody agrees that
 211 .BR posix_memalign ()
 212 is declared in \fI<stdlib.h>\fP.
 213 .PP
 214 On some systems
 215 .BR memalign ()
 216 is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP.
 217 .PP
 218 According to SUSv2,
 219 .BR valloc ()
 220 is declared in \fI<stdlib.h>\fP.
 221 .\" Libc4,5 and
 222 Glibc declares it in \fI<malloc.h>\fP, and also in
 223 \fI<stdlib.h>\fP
 224 if suitable feature test macros are defined (see above).
 225 .SH NOTES
 226 On many systems there are alignment restrictions, for example, on buffers
 227 used for direct block device I/O.
 228 POSIX specifies the
 229 .I "pathconf(path,_PC_REC_XFER_ALIGN)"
 230 call that tells what alignment is needed.
 231 Now one can use
 232 .BR posix_memalign ()
 233 to satisfy this requirement.
 234 .PP
 235 .BR posix_memalign ()
 236 verifies that
 237 .I alignment
 238 matches the requirements detailed above.
 239 .BR memalign ()
 240 may not check that the
 241 .I alignment
 242 argument is correct.
 243 .PP
 244 POSIX requires that memory obtained from
 245 .BR posix_memalign ()
 246 can be freed using
 247 .BR free (3).
 248 Some systems provide no way to reclaim memory allocated with
 249 .BR memalign ()
 250 or
 251 .BR valloc ()
 252 (because one can pass to
 253 .BR free (3)
 254 only a pointer obtained from
 255 .BR malloc (3),
 256 while, for example,
 257 .BR memalign ()
 258 would call
 259 .BR malloc (3)
 260 and then align the obtained value).
 261 .\" Other systems allow passing the result of
 262 .\" .IR valloc ()
 263 .\" to
 264 .\" .IR free (3),
 265 .\" but not to
 266 .\" .IR realloc (3).
 267 The glibc implementation
 268 allows memory obtained from any of these functions to be
 269 reclaimed with
 270 .BR free (3).
 271 .PP
 272 The glibc
 273 .BR malloc (3)
 274 always returns 8-byte aligned memory addresses, so these functions are
 275 needed only if you require larger alignment values.
 276 .SH SEE ALSO
 277 .BR brk (2),
 278 .BR getpagesize (2),
 279 .BR free (3),
 280 .BR malloc (3)