]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" (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. | |
c13182ef | 12 | .\" |
fea681da MK |
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. | |
c13182ef | 20 | .\" |
fea681da MK |
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 2003-08-22 "GNU" "Linux Programmer's Manual" | |
27 | .SH NAME | |
28 | posix_memalign, memalign, valloc \- Allocate aligned memory | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #define _XOPEN_SOURCE 600 | |
32 | .B #include <stdlib.h> | |
33 | .sp | |
34 | .BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); | |
35 | .sp | |
36 | .B #include <malloc.h> | |
37 | .sp | |
38 | .BI "void *valloc(size_t " size ); | |
39 | .BI "void *memalign(size_t " boundary ", size_t " size ); | |
fea681da MK |
40 | .fi |
41 | .SH DESCRIPTION | |
42 | The function | |
63aa9df0 | 43 | .BR posix_memalign () |
fea681da MK |
44 | allocates |
45 | .I size | |
46 | bytes and places the address of the allocated memory in | |
a5e0a0e4 | 47 | .IR "*memptr" . |
fea681da | 48 | The address of the allocated memory will be a multiple of |
a5e0a0e4 | 49 | .IR "alignment" , |
fea681da MK |
50 | which must be a power of two and a multiple of |
51 | .IR "sizeof(void *)". | |
52 | ||
53 | The obsolete function | |
63aa9df0 | 54 | .BR memalign () |
fea681da MK |
55 | allocates |
56 | .I size | |
57 | bytes and returns a pointer to the allocated memory. | |
58 | The memory address will be a multiple of | |
a5e0a0e4 | 59 | .IR "boundary" , |
fea681da MK |
60 | which must be a power of two. |
61 | ||
62 | The obsolete function | |
63aa9df0 | 63 | .BR valloc () |
fea681da MK |
64 | allocates |
65 | .I size | |
66 | bytes and returns a pointer to the allocated memory. | |
67 | The memory address will be a multiple of the page size. | |
68 | It is equivalent to | |
69 | .IR "memalign(sysconf(_SC_PAGESIZE),size)" . | |
70 | ||
71 | For all three routines, the memory is not zeroed. | |
fea681da | 72 | .SH "RETURN VALUE" |
63aa9df0 | 73 | .BR memalign () |
fea681da | 74 | and |
63aa9df0 | 75 | .BR valloc () |
8478ee02 | 76 | return the pointer to the allocated memory, or NULL if the request fails. |
fea681da | 77 | |
63aa9df0 | 78 | .BR posix_memalign () |
fea681da | 79 | returns zero on success, or one of the error values listed in the |
c13182ef MK |
80 | next section on failure. |
81 | Note that | |
fea681da MK |
82 | .IR errno |
83 | is not set. | |
fea681da MK |
84 | .SH "ERRORS" |
85 | .TP | |
86 | .B EINVAL | |
87 | The | |
88 | .IR alignment | |
89 | parameter was not a power of two, or was not a multiple of | |
90 | .IR "sizeof(void *)" . | |
91 | .TP | |
92 | .B ENOMEM | |
93 | There was insufficient memory to fulfill the allocation request. | |
2b2581ee MK |
94 | .SH VERSIONS |
95 | The functions | |
96 | .BR memalign () | |
97 | and | |
98 | .BR valloc () | |
99 | have been available in all Linux libc libraries. | |
100 | The function | |
101 | .BR posix_memalign () | |
102 | is available since glibc 2.1.91. | |
103 | .SH "CONFORMING TO" | |
104 | The function | |
105 | .BR valloc () | |
106 | appeared in 3.0BSD. | |
107 | It is documented as being obsolete in 4.3BSD, | |
108 | and as legacy in SUSv2. | |
109 | It does not appear in POSIX.1-2001. | |
110 | The function | |
111 | .BR memalign () | |
112 | appears in SunOS 4.1.3 but not in 4.4BSD. | |
113 | The function | |
114 | .BR posix_memalign () | |
115 | comes from POSIX.1d. | |
116 | .SS Headers | |
117 | Everybody agrees that | |
118 | .BR posix_memalign () | |
119 | is declared in <stdlib.h>. | |
120 | In order to declare it, glibc needs | |
121 | _GNU_SOURCE defined, or _XOPEN_SOURCE defined to a value not less than 600. | |
122 | ||
123 | On some systems | |
124 | .BR memalign () | |
125 | is declared in <stdlib.h> instead of <malloc.h>. | |
126 | ||
127 | According to SUSv2, | |
128 | .BR valloc () | |
129 | is declared in <stdlib.h>. | |
130 | Libc4,5 and glibc declare it in <malloc.h> and perhaps also in <stdlib.h> | |
131 | (namely, if _GNU_SOURCE is defined, or _BSD_SOURCE is defined, or, | |
132 | for glibc, if _XOPEN_SOURCE_EXTENDED is defined, or, equivalently, | |
133 | _XOPEN_SOURCE is defined to a value not less than 500). | |
fea681da | 134 | .SH NOTES |
75b94dc3 | 135 | On many systems there are alignment restrictions, for example, on buffers |
c13182ef MK |
136 | used for direct block device I/O. |
137 | POSIX specifies the | |
fea681da | 138 | .I "pathconf(path,_PC_REC_XFER_ALIGN)" |
c13182ef MK |
139 | call that tells what alignment is needed. |
140 | Now one can use | |
fea681da MK |
141 | .BR posix_memalign () |
142 | to satisfy this requirement. | |
143 | ||
144 | .BR posix_memalign () | |
145 | verifies that | |
146 | .IR alignment | |
147 | matches the requirements detailed above. | |
63aa9df0 | 148 | .BR memalign () |
fea681da MK |
149 | may not check that the |
150 | .IR boundary | |
151 | parameter is correct. | |
152 | ||
153 | POSIX requires that memory obtained from | |
63aa9df0 | 154 | .BR posix_memalign () |
fea681da | 155 | can be freed using |
fb186734 | 156 | .BR free (3). |
fea681da | 157 | Some systems provide no way to reclaim memory allocated with |
31e9a9ec | 158 | .BR memalign () |
fea681da | 159 | or |
31e9a9ec | 160 | .BR valloc () |
fea681da | 161 | (because one can only pass to |
fb186734 | 162 | .BR free (3) |
fea681da | 163 | a pointer gotten from |
fb186734 | 164 | .BR malloc (3), |
75b94dc3 | 165 | while, for example, |
31e9a9ec | 166 | .BR memalign () |
fea681da | 167 | would call |
fb186734 | 168 | .BR malloc (3) |
fea681da MK |
169 | and then align the obtained value). |
170 | .\" Other systems allow passing the result of | |
171 | .\" .IR valloc () | |
172 | .\" to | |
fb186734 | 173 | .\" .IR free (3), |
fea681da | 174 | .\" but not to |
fb186734 | 175 | .\" .IR realloc (3). |
fea681da MK |
176 | GNU libc allows memory obtained from any of these three routines to be |
177 | reclaimed with | |
fb186734 | 178 | .BR free (3). |
fea681da MK |
179 | |
180 | GNU libc | |
fb186734 | 181 | .BR malloc (3) |
fea681da MK |
182 | always returns 8-byte aligned memory addresses, so these routines are only |
183 | needed if you require larger alignment values. | |
fea681da MK |
184 | .SH "SEE ALSO" |
185 | .BR brk (2), | |
186 | .BR getpagesize (2), | |
187 | .BR free (3), | |
50e5322c | 188 | .BR malloc (3), |
a8e7c990 | 189 | .BR feature_test_macros (7) |