]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) | |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
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_END | |
24 | .\" | |
25 | .\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) | |
26 | .\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 | |
27 | .\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) | |
28 | .\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). | |
29 | .\" | |
30 | .\" FIXME . Review http://austingroupbugs.net/view.php?id=374 | |
31 | .\" to see what changes are required on this page. | |
32 | .\" | |
33 | .TH MALLOC 3 2017-09-15 "GNU" "Linux Programmer's Manual" | |
34 | .SH NAME | |
35 | malloc, free, calloc, realloc \- allocate and free dynamic memory | |
36 | .SH SYNOPSIS | |
37 | .nf | |
38 | .B #include <stdlib.h> | |
39 | .PP | |
40 | .BI "void *malloc(size_t " "size" ); | |
41 | .BI "void free(void " "*ptr" ); | |
42 | .BI "void *calloc(size_t " "nmemb" ", size_t " "size" ); | |
43 | .BI "void *realloc(void " "*ptr" ", size_t " "size" ); | |
44 | .BI "void *reallocarray(void " "*ptr" ", size_t " nmemb ", size_t " "size" ); | |
45 | .fi | |
46 | .PP | |
47 | .in -4n | |
48 | Feature Test Macro Requirements for glibc (see | |
49 | .BR feature_test_macros (7)): | |
50 | .in | |
51 | .PP | |
52 | .BR reallocarray (): | |
53 | .ad l | |
54 | _GNU_SOURCE | |
55 | .RE | |
56 | Since glibc 2.29: | |
57 | _DEFAULT_SOURCE | |
58 | Glibc 2.28 and earlier: | |
59 | _GNU_SOURCE | |
60 | .ad | |
61 | .SH DESCRIPTION | |
62 | .PP | |
63 | The | |
64 | .BR malloc () | |
65 | function allocates | |
66 | .I size | |
67 | bytes and returns a pointer to the allocated memory. | |
68 | .IR "The memory is not initialized" . | |
69 | If | |
70 | .I size | |
71 | is 0, then | |
72 | .BR malloc () | |
73 | returns either NULL, | |
74 | .\" glibc does this: | |
75 | or a unique pointer value that can later be successfully passed to | |
76 | .BR free (). | |
77 | .PP | |
78 | The | |
79 | .BR free () | |
80 | function frees the memory space pointed to by | |
81 | .IR ptr , | |
82 | which must have been returned by a previous call to | |
83 | .BR malloc (), | |
84 | .BR calloc (), | |
85 | or | |
86 | .BR realloc (). | |
87 | Otherwise, or if | |
88 | .I free(ptr) | |
89 | has already been called before, undefined behavior occurs. | |
90 | If | |
91 | .I ptr | |
92 | is NULL, no operation is performed. | |
93 | .PP | |
94 | The | |
95 | .BR calloc () | |
96 | function allocates memory for an array of | |
97 | .I nmemb | |
98 | elements of | |
99 | .I size | |
100 | bytes each and returns a pointer to the allocated memory. | |
101 | The memory is set to zero. | |
102 | If | |
103 | .I nmemb | |
104 | or | |
105 | .I size | |
106 | is 0, then | |
107 | .BR calloc () | |
108 | returns either NULL, | |
109 | .\" glibc does this: | |
110 | or a unique pointer value that can later be successfully passed to | |
111 | .BR free (). | |
112 | If the multiplication of | |
113 | .I nmemb | |
114 | and | |
115 | .I size | |
116 | would result in integer overflow, then | |
117 | .BR calloc () | |
118 | returns an error. | |
119 | By contrast, | |
120 | an integer overflow would not be detected in the following call to | |
121 | .BR malloc (), | |
122 | with the result that an incorrectly sized block of memory would be allocated: | |
123 | .PP | |
124 | .in +4n | |
125 | .EX | |
126 | malloc(nmemb * size); | |
127 | .EE | |
128 | .in | |
129 | .PP | |
130 | The | |
131 | .BR realloc () | |
132 | function changes the size of the memory block pointed to by | |
133 | .I ptr | |
134 | to | |
135 | .I size | |
136 | bytes. | |
137 | The contents will be unchanged in the range from the start of the region | |
138 | up to the minimum of the old and new sizes. | |
139 | If the new size is larger than the old size, the added memory will | |
140 | .I not | |
141 | be initialized. | |
142 | If | |
143 | .I ptr | |
144 | is NULL, then the call is equivalent to | |
145 | .IR malloc(size) , | |
146 | for all values of | |
147 | .IR size ; | |
148 | if | |
149 | .I size | |
150 | is equal to zero, | |
151 | and | |
152 | .I ptr | |
153 | is not NULL, then the call is equivalent to | |
154 | .IR free(ptr) . | |
155 | Unless | |
156 | .I ptr | |
157 | is NULL, it must have been returned by an earlier call to | |
158 | .BR malloc (), | |
159 | .BR calloc (), | |
160 | or | |
161 | .BR realloc (). | |
162 | If the area pointed to was moved, a | |
163 | .I free(ptr) | |
164 | is done. | |
165 | .PP | |
166 | The | |
167 | .BR reallocarray () | |
168 | function changes the size of the memory block pointed to by | |
169 | .I ptr | |
170 | to be large enough for an array of | |
171 | .I nmemb | |
172 | elements, each of which is | |
173 | .I size | |
174 | bytes. | |
175 | It is equivalent to the call | |
176 | .PP | |
177 | .in +4n | |
178 | realloc(ptr, nmemb * size); | |
179 | .in | |
180 | .PP | |
181 | However, unlike that | |
182 | .BR realloc () | |
183 | call, | |
184 | .BR reallocarray () | |
185 | fails safely in the case where the multiplication would overflow. | |
186 | If such an overflow occurs, | |
187 | .BR reallocarray () | |
188 | returns NULL, sets | |
189 | .I errno | |
190 | to | |
191 | .BR ENOMEM , | |
192 | and leaves the original block of memory unchanged. | |
193 | .SH RETURN VALUE | |
194 | The | |
195 | .BR malloc () | |
196 | and | |
197 | .BR calloc () | |
198 | functions return a pointer to the allocated memory, | |
199 | which is suitably aligned for any built-in type. | |
200 | On error, these functions return NULL. | |
201 | NULL may also be returned by a successful call to | |
202 | .BR malloc () | |
203 | with a | |
204 | .I size | |
205 | of zero, | |
206 | or by a successful call to | |
207 | .BR calloc () | |
208 | with | |
209 | .I nmemb | |
210 | or | |
211 | .I size | |
212 | equal to zero. | |
213 | .PP | |
214 | The | |
215 | .BR free () | |
216 | function returns no value. | |
217 | .PP | |
218 | The | |
219 | .BR realloc () | |
220 | function returns a pointer to the newly allocated memory, which is suitably | |
221 | aligned for any built-in type and may be different from | |
222 | .IR ptr , | |
223 | or NULL if the request fails. | |
224 | If | |
225 | .I size | |
226 | was equal to 0, either NULL or a pointer suitable to be passed to | |
227 | .BR free () | |
228 | is returned. | |
229 | If | |
230 | .BR realloc () | |
231 | fails, the original block is left untouched; it is not freed or moved. | |
232 | .PP | |
233 | On success, the | |
234 | .BR reallocarray () | |
235 | function returns a pointer to the newly allocated memory. | |
236 | On failure, | |
237 | it returns NULL and the original block of memory is left untouched. | |
238 | .SH ERRORS | |
239 | .BR calloc (), | |
240 | .BR malloc (), | |
241 | .BR realloc (), | |
242 | and | |
243 | .BR reallocarray () | |
244 | can fail with the following error: | |
245 | .TP | |
246 | .B ENOMEM | |
247 | Out of memory. | |
248 | Possibly, the application hit the | |
249 | .BR RLIMIT_AS | |
250 | or | |
251 | .BR RLIMIT_DATA | |
252 | limit described in | |
253 | .BR getrlimit (2). | |
254 | .SH ATTRIBUTES | |
255 | For an explanation of the terms used in this section, see | |
256 | .BR attributes (7). | |
257 | .TS | |
258 | allbox; | |
259 | lbw20 lb lb | |
260 | l l l. | |
261 | Interface Attribute Value | |
262 | T{ | |
263 | .BR malloc (), | |
264 | .BR free (), | |
265 | .br | |
266 | .BR calloc (), | |
267 | .BR realloc () | |
268 | T} Thread safety MT-Safe | |
269 | .TE | |
270 | .SH CONFORMING TO | |
271 | .BR malloc (), | |
272 | .BR free (), | |
273 | .BR calloc (), | |
274 | .BR realloc (): | |
275 | POSIX.1-2001, POSIX.1-2008, C89, C99. | |
276 | .PP | |
277 | .BR reallocarray () | |
278 | is a nonstandard extension that first appeared in OpenBSD 5.6 and FreeBSD 11.0. | |
279 | .SH NOTES | |
280 | By default, Linux follows an optimistic memory allocation strategy. | |
281 | This means that when | |
282 | .BR malloc () | |
283 | returns non-NULL there is no guarantee that the memory really | |
284 | is available. | |
285 | In case it turns out that the system is out of memory, | |
286 | one or more processes will be killed by the OOM killer. | |
287 | For more information, see the description of | |
288 | .IR /proc/sys/vm/overcommit_memory | |
289 | and | |
290 | .IR /proc/sys/vm/oom_adj | |
291 | in | |
292 | .BR proc (5), | |
293 | and the Linux kernel source file | |
294 | .IR Documentation/vm/overcommit-accounting.rst . | |
295 | .PP | |
296 | Normally, | |
297 | .BR malloc () | |
298 | allocates memory from the heap, and adjusts the size of the heap | |
299 | as required, using | |
300 | .BR sbrk (2). | |
301 | When allocating blocks of memory larger than | |
302 | .B MMAP_THRESHOLD | |
303 | bytes, the glibc | |
304 | .BR malloc () | |
305 | implementation allocates the memory as a private anonymous mapping using | |
306 | .BR mmap (2). | |
307 | .B MMAP_THRESHOLD | |
308 | is 128\ kB by default, but is adjustable using | |
309 | .BR mallopt (3). | |
310 | Prior to Linux 4.7 | |
311 | allocations performed using | |
312 | .BR mmap (2) | |
313 | were unaffected by the | |
314 | .B RLIMIT_DATA | |
315 | resource limit; | |
316 | since Linux 4.7, this limit is also enforced for allocations performed using | |
317 | .BR mmap (2). | |
318 | .PP | |
319 | To avoid corruption in multithreaded applications, | |
320 | mutexes are used internally to protect the memory-management | |
321 | data structures employed by these functions. | |
322 | In a multithreaded application in which threads simultaneously | |
323 | allocate and free memory, | |
324 | there could be contention for these mutexes. | |
325 | To scalably handle memory allocation in multithreaded applications, | |
326 | glibc creates additional | |
327 | .IR "memory allocation arenas" | |
328 | if mutex contention is detected. | |
329 | Each arena is a large region of memory that is internally allocated | |
330 | by the system | |
331 | (using | |
332 | .BR brk (2) | |
333 | or | |
334 | .BR mmap (2)), | |
335 | and managed with its own mutexes. | |
336 | .PP | |
337 | SUSv2 requires | |
338 | .BR malloc (), | |
339 | .BR calloc (), | |
340 | and | |
341 | .BR realloc () | |
342 | to set | |
343 | .I errno | |
344 | to | |
345 | .B ENOMEM | |
346 | upon failure. | |
347 | Glibc assumes that this is done | |
348 | (and the glibc versions of these routines do this); if you | |
349 | use a private malloc implementation that does not set | |
350 | .IR errno , | |
351 | then certain library routines may fail without having | |
352 | a reason in | |
353 | .IR errno . | |
354 | .PP | |
355 | Crashes in | |
356 | .BR malloc (), | |
357 | .BR calloc (), | |
358 | .BR realloc (), | |
359 | or | |
360 | .BR free () | |
361 | are almost always related to heap corruption, such as overflowing | |
362 | an allocated chunk or freeing the same pointer twice. | |
363 | .PP | |
364 | The | |
365 | .BR malloc () | |
366 | implementation is tunable via environment variables; see | |
367 | .BR mallopt (3) | |
368 | for details. | |
369 | .SH SEE ALSO | |
370 | .\" http://g.oswego.edu/dl/html/malloc.html | |
371 | .\" A Memory Allocator - by Doug Lea | |
372 | .\" | |
373 | .\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html | |
374 | .\" Linux Heap, Contention in free() - David Boreham | |
375 | .\" | |
376 | .\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html | |
377 | .\" malloc() Performance in a Multithreaded Linux Environment - | |
378 | .\" Check Lever, David Boreham | |
379 | .\" | |
380 | .ad l | |
381 | .nh | |
382 | .BR valgrind (1), | |
383 | .BR brk (2), | |
384 | .BR mmap (2), | |
385 | .BR alloca (3), | |
386 | .BR malloc_get_state (3), | |
387 | .BR malloc_info (3), | |
388 | .BR malloc_trim (3), | |
389 | .BR malloc_usable_size (3), | |
390 | .BR mallopt (3), | |
391 | .BR mcheck (3), | |
392 | .BR mtrace (3), | |
393 | .BR posix_memalign (3) | |
394 | .PP | |
395 | For details of the GNU C library implementation, see | |
396 | .UR https://sourceware.org/glibc/wiki/MallocInternals | |
397 | .UE . |