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  2010-09-20 "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 .sp
  50 .BR valloc ():
  51 .br
  52 .PD 0
  53 .RS 4
  54 .TP 4
  55 Since glibc 2.12:
  56 .nf
  57 _BSD_SOURCE ||
  58     (_XOPEN_SOURCE\ >=\ 500 ||
  59         _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) &&
  60     !(_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600)
  61 .br
  62 .fi
  63 .TP
  64 Before glibc 2.12:
  65 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
  66 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  67 .RE
  68 .PD
  69 .ad b
  70 .SH DESCRIPTION
  71 The function
  72 .BR posix_memalign ()
  73 allocates
  74 .I size
  75 bytes and places the address of the allocated memory in
  76 .IR "*memptr" .
  77 The address of the allocated memory will be a multiple of
  78 .IR "alignment" ,
  79 which must be a power of two and a multiple of
  80 .IR "sizeof(void *)".
  81 If
  82 .I size
  83 is 0, then
  84 .BR posix_memalign ()
  85 returns either NULL,
  86 .\" glibc does this:
  87 or a unique pointer value that can later be successfully passed to
  88 .BR free (3).
  89
  90 The obsolete function
  91 .BR memalign ()
  92 allocates
  93 .I size
  94 bytes and returns a pointer to the allocated memory.
  95 The memory address will be a multiple of
  96 .IR "boundary" ,
  97 which must be a power of two.
  98 .\" The behavior of memalign() for size==0 is as for posix_memalign()
  99 .\" but no standards govern this.
 100
 101 The obsolete function
 102 .BR valloc ()
 103 allocates
 104 .I size
 105 bytes and returns a pointer to the allocated memory.
 106 The memory address will be a multiple of the page size.
 107 It is equivalent to
 108 .IR "memalign(sysconf(_SC_PAGESIZE),size)" .
 109
 110 For all three routines, the memory is not zeroed.
 111 .SH "RETURN VALUE"
 112 .BR memalign ()
 113 and
 114 .BR valloc ()
 115 return the pointer to the allocated memory, or NULL if the request fails.
 116
 117 .BR posix_memalign ()
 118 returns zero on success, or one of the error values listed in the
 119 next section on failure.
 120 Note that
 121 .I errno
 122 is not set.
 123 .SH "ERRORS"
 124 .TP
 125 .B EINVAL
 126 The
 127 .I alignment
 128 argument was not a power of two, or was not a multiple of
 129 .IR "sizeof(void *)" .
 130 .TP
 131 .B ENOMEM
 132 There was insufficient memory to fulfill the allocation request.
 133 .SH VERSIONS
 134 The functions
 135 .BR memalign ()
 136 and
 137 .BR valloc ()
 138 have been available in all Linux libc libraries.
 139 The function
 140 .BR posix_memalign ()
 141 is available since glibc 2.1.91.
 142 .SH "CONFORMING TO"
 143 The function
 144 .BR valloc ()
 145 appeared in 3.0BSD.
 146 It is documented as being obsolete in 4.3BSD,
 147 and as legacy in SUSv2.
 148 It does not appear in POSIX.1-2001.
 149 The function
 150 .BR memalign ()
 151 appears in SunOS 4.1.3 but not in 4.4BSD.
 152 The function
 153 .BR posix_memalign ()
 154 comes from POSIX.1d.
 155 .SS Headers
 156 Everybody agrees that
 157 .BR posix_memalign ()
 158 is declared in \fI<stdlib.h>\fP.
 159
 160 On some systems
 161 .BR memalign ()
 162 is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP.
 163
 164 According to SUSv2,
 165 .BR valloc ()
 166 is declared in \fI<stdlib.h>\fP.
 167 Libc4,5 and glibc declare it in \fI<malloc.h>\fP and perhaps also in
 168 \fI<stdlib.h>\fP
 169 (namely, if
 170 .B _GNU_SOURCE
 171 is defined, or
 172 .B _BSD_SOURCE
 173 is defined, or,
 174 for glibc, if
 175 .B _XOPEN_SOURCE_EXTENDED
 176 is defined, or, equivalently,
 177 .B _XOPEN_SOURCE
 178 is defined to a value not less than 500).
 179 .SH NOTES
 180 On many systems there are alignment restrictions, for example, on buffers
 181 used for direct block device I/O.
 182 POSIX specifies the
 183 .I "pathconf(path,_PC_REC_XFER_ALIGN)"
 184 call that tells what alignment is needed.
 185 Now one can use
 186 .BR posix_memalign ()
 187 to satisfy this requirement.
 188
 189 .BR posix_memalign ()
 190 verifies that
 191 .I alignment
 192 matches the requirements detailed above.
 193 .BR memalign ()
 194 may not check that the
 195 .I boundary
 196 argument is correct.
 197
 198 POSIX requires that memory obtained from
 199 .BR posix_memalign ()
 200 can be freed using
 201 .BR free (3).
 202 Some systems provide no way to reclaim memory allocated with
 203 .BR memalign ()
 204 or
 205 .BR valloc ()
 206 (because one can only pass to
 207 .BR free (3)
 208 a pointer gotten from
 209 .BR malloc (3),
 210 while, for example,
 211 .BR memalign ()
 212 would call
 213 .BR malloc (3)
 214 and then align the obtained value).
 215 .\" Other systems allow passing the result of
 216 .\" .IR valloc ()
 217 .\" to
 218 .\" .IR free (3),
 219 .\" but not to
 220 .\" .IR realloc (3).
 221 The glibc implementation
 222 allows memory obtained from any of these three routines to be
 223 reclaimed with
 224 .BR free (3).
 225
 226 The glibc
 227 .BR malloc (3)
 228 always returns 8-byte aligned memory addresses, so these routines are only
 229 needed if you require larger alignment values.
 230 .SH "SEE ALSO"
 231 .BR brk (2),
 232 .BR getpagesize (2),
 233 .BR free (3),
 234 .BR malloc (3)