Debian Codegraph @

upstream/debian-unstable/man3/malloc.3

raw
1 '\" t
2 .\" Copyright 1993, Thomas Koenig <[email protected]>
3 .\" Copyright 2007-2018, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .\" FIXME . Review http://austingroupbugs.net/view.php?id=374
9 .\" to see what changes are required on this page.
10 .\"
11 .TH malloc 3 2026-02-08 "Linux man-pages 6.18"
12 .SH NAME
13 malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic 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 "void *malloc(size_t " size );
22 .BI "void free(void *_Nullable " p );
23 .BI "void *calloc(size_t " n ", size_t " size );
24 .BI "void *realloc(void *_Nullable " p ", size_t " size );
25 .BI "void *reallocarray(void *_Nullable " p ", size_t " n ", size_t " size );
26 .fi
27 .P
28 .RS -4
29 Feature Test Macro Requirements for glibc (see
30 .BR feature_test_macros (7)):
31 .RE
32 .P
33 .BR reallocarray ():
34 .nf
35 Since glibc 2.29:
36 _DEFAULT_SOURCE
37 glibc 2.28 and earlier:
38 _GNU_SOURCE
39 .fi
40 .SH DESCRIPTION
41 .SS malloc()
42 The
43 .BR malloc ()
44 function allocates
45 .I size
46 bytes and returns a pointer to the allocated memory.
47 .IR "The memory is not initialized" .
48 If
49 .I size
50 is 0, then
51 .BR malloc ()
52 returns a unique pointer value that can later be successfully passed to
53 .BR free ().
54 (See "Nonportable behavior" for portability issues.)
55 .SS free()
56 The
57 .BR free ()
58 function frees the memory space pointed to by
59 .IR p ,
60 which must have been returned by a previous call to
61 .BR malloc ()
62 or related functions.
63 Otherwise, or if
64 .I p
65 has already been freed, undefined behavior occurs.
66 If
67 .I p
68 is NULL, no operation is performed.
69 .SS calloc()
70 The
71 .BR calloc ()
72 function allocates memory for an array of
73 .I n
74 elements of
75 .I size
76 bytes each and returns a pointer to the allocated memory.
77 The memory is set to zero.
78 If
79 .I n
80 or
81 .I size
82 is 0, then
83 .BR calloc ()
84 returns a unique pointer value that can later be successfully passed to
85 .BR free ().
86 .P
87 If the multiplication of
88 .I n
89 and
90 .I size
91 would result in integer overflow, then
92 .BR calloc ()
93 returns an error.
94 By contrast,
95 an integer overflow would not be detected in the following call to
96 .BR malloc (),
97 with the result that an incorrectly sized block of memory would be allocated:
98 .P
99 .in +4n
100 .EX
101 malloc(n * size);
102 .EE
103 .in
104 .SS realloc()
105 The
106 .BR realloc ()
107 function changes the size of the memory block pointed to by
108 .I p
109 to
110 .I size
111 bytes.
112 The contents of the memory
113 will be unchanged in the range from the start of the region
114 up to the minimum of the old and new sizes.
115 If the new size is larger than the old size, the added memory will
116 .I not
117 be initialized.
118 .P
119 If
120 .I p
121 is NULL, then the call is equivalent to
122 .IR malloc(size) ,
123 for all values of
124 .IR size .
125 .P
126 If
127 .I size
128 is equal to zero,
129 and
130 .I p
131 is not NULL, then the call is equivalent to
132 .I free(p)
133 (but see "Nonportable behavior" for portability issues).
134 .P
135 Unless
136 .I p
137 is NULL, it must have been returned by an earlier call to
138 .B malloc
139 or related functions.
140 If the area pointed to was moved, a
141 .I free(p)
142 is done.
143 .SS reallocarray()
144 The
145 .BR reallocarray ()
146 function changes the size of (and possibly moves)
147 the memory block pointed to by
148 .I p
149 to be large enough for an array of
150 .I n
151 elements, each of which is
152 .I size
153 bytes.
154 It is equivalent to the call
155 .P
156 .in +4n
157 .EX
158 realloc(p, n * size);
159 .EE
160 .in
161 .P
162 However, unlike that
163 .BR realloc ()
164 call,
165 .BR reallocarray ()
166 fails safely in the case where the multiplication would overflow.
167 If such an overflow occurs,
168 .BR reallocarray ()
169 returns an error.
170 .SH RETURN VALUE
171 The
172 .BR malloc (),
173 .BR calloc (),
174 .BR realloc (),
175 and
176 .BR reallocarray ()
177 functions return a pointer to the allocated memory,
178 which is suitably aligned for any type that fits into
179 the requested size or less.
180 On error, these functions return NULL and set
181 .IR errno .
182 Attempting to allocate more than
183 .B PTRDIFF_MAX
184 bytes is considered an error, as an object that large
185 could cause later pointer subtraction to overflow.
186 .P
187 The
188 .BR free ()
189 function returns no value, and preserves
190 .IR errno .
191 .P
192 The
193 .BR realloc ()
194 and
195 .BR reallocarray ()
196 functions return NULL if
197 .I p
198 is not NULL and the requested size is zero;
199 this is not considered an error.
200 (See "Nonportable behavior" for portability issues.)
201 Otherwise, the returned pointer may be the same as
202 .I p
203 if the allocation was not moved
204 (e.g., there was room to expand the allocation in-place), or different from
205 .I p
206 if the allocation was moved to a new address.
207 If these functions fail,
208 the original block is left untouched;
209 it is not freed or moved.
210 .SH ERRORS
211 .BR calloc (),
212 .BR malloc (),
213 .BR realloc (),
214 and
215 .BR reallocarray ()
216 can fail with the following error:
217 .TP
218 .B ENOMEM
219 Out of memory.
220 Possibly, the application hit the
221 .B RLIMIT_AS
222 or
223 .B RLIMIT_DATA
224 limit described in
225 .BR getrlimit (2).
226 Another reason could be that
227 the number of mappings created by the caller process
228 exceeded the limit specified by
229 .IR /proc/sys/vm/max_map_count .
230 .SH ATTRIBUTES
231 For an explanation of the terms used in this section, see
232 .BR attributes (7).
233 .TS
234 allbox;
235 lbx lb lb
236 l l l.
237 Interface Attribute Value
238 T{
239 .na
240 .nh
241 .BR malloc (),
242 .BR free (),
243 .BR calloc (),
244 .BR realloc ()
245 T} Thread safety MT-Safe
246 .TE
247 .SH STANDARDS
248 .TP
249 .BR malloc ()
250 .TQ
251 .BR free ()
252 .TQ
253 .BR calloc ()
254 .TQ
255 .BR realloc ()
256 C23, POSIX.1-2024.
257 .TP
258 .BR reallocarray ()
259 POSIX.1-2024.
260 .SS realloc(p, 0)
261 The behavior of
262 .I realloc(p,\~0)
263 in glibc doesn't conform to any of
264 C99,
265 C11,
266 POSIX.1-2001,
267 POSIX.1-2004,
268 POSIX.1-2008,
269 POSIX.1-2013,
270 POSIX.1-2017,
271 or POSIX.1-2024.
272 The C17 specification was changed to make it conforming,
273 but that specification made it
274 impossible to write code that reliably
275 determines if the input pointer is freed after
276 .IR realloc(p,\~0) ,
277 and C23 changed it again to make this undefined behavior,
278 acknowledging that the C17 specification was broad enough,
279 so that undefined behavior wasn't worse than that.
280 .P
281 .BR reallocarray ()
282 suffers the same issues in glibc.
283 .P
284 musl libc and the BSDs conform to all versions of ISO C and POSIX.1.
285 .P
286 gnulib provides the
287 .I realloc-posix
288 module,
289 which provides wrappers
290 .BR realloc ()
291 and
292 .BR reallocarray ()
293 that conform to all versions of ISO C and POSIX.1.
294 .P
295 There's a proposal to standardize the BSD behavior:
296 .UR https:\://www.open\-std.org/\:jtc1/\:sc22/\:wg14/\:www/\:docs/\:n3621.txt
297 .UE .
298 .SH HISTORY
299 .TP
300 .BR malloc ()
301 .TQ
302 .BR free ()
303 .TQ
304 .BR calloc ()
305 .TQ
306 .BR realloc ()
307 POSIX.1-2001, C89.
308 .TP
309 .BR reallocarray ()
310 glibc 2.26.
311 OpenBSD 5.6, FreeBSD 11.0.
312 .P
313 .BR malloc ()
314 and related functions rejected sizes greater than
315 .B PTRDIFF_MAX
316 starting in glibc 2.30.
317 .P
318 .BR free ()
319 preserved
320 .I errno
321 starting in glibc 2.33.
322 .SS realloc(p,\~0)
323 C89 was ambiguous in its specification of
324 .IR realloc(p,\~0) .
325 C99 partially fixed this.
326 .P
327 The original implementation in glibc would have been conforming to C99.
328 However, and ironically,
329 trying to comply with C99 before the standard was released,
330 glibc changed its behavior in glibc 2.1.1 into something that ended up
331 not conforming to the final C99 specification
332 (but this is debated,
333 as the wording of the standard seems self-contradicting).
334 .SH NOTES
335 By default, Linux follows an optimistic memory allocation strategy.
336 This means that when
337 .BR malloc ()
338 returns non-NULL there is no guarantee that the memory really
339 is available.
340 In case it turns out that the system is out of memory,
341 one or more processes will be killed by the OOM killer.
342 For more information, see the description of
343 .I /proc/sys/vm/overcommit_memory
344 and
345 .I /proc/sys/vm/oom_adj
346 in
347 .BR proc (5),
348 and the Linux kernel source file
349 .IR Documentation/vm/overcommit\-accounting.rst .
350 .P
351 Normally,
352 .BR malloc ()
353 allocates memory from the heap, and adjusts the size of the heap
354 as required, using
355 .BR sbrk (2).
356 When allocating blocks of memory larger than
357 .B MMAP_THRESHOLD
358 bytes, the glibc
359 .BR malloc ()
360 implementation allocates the memory as a private anonymous mapping using
361 .BR mmap (2).
362 .B MMAP_THRESHOLD
363 is 128\ kB by default, but is adjustable using
364 .BR mallopt (3).
365 Prior to Linux 4.7
366 allocations performed using
367 .BR mmap (2)
368 were unaffected by the
369 .B RLIMIT_DATA
370 resource limit;
371 since Linux 4.7, this limit is also enforced for allocations performed using
372 .BR mmap (2).
373 .P
374 To avoid corruption in multithreaded applications,
375 mutexes are used internally to protect the memory-management
376 data structures employed by these functions.
377 In a multithreaded application in which threads simultaneously
378 allocate and free memory,
379 there could be contention for these mutexes.
380 To scalably handle memory allocation in multithreaded applications,
381 glibc creates additional
382 .I memory allocation arenas
383 if mutex contention is detected.
384 Each arena is a large region of memory that is internally allocated
385 by the system
386 (using
387 .BR brk (2)
388 or
389 .BR mmap (2)),
390 and managed with its own mutexes.
391 .P
392 If your program uses a private memory allocator,
393 it should do so by replacing
394 .BR malloc (),
395 .BR free (),
396 .BR calloc (),
397 and
398 .BR realloc ().
399 The replacement functions must implement the documented glibc behaviors,
400 including
401 .I errno
402 handling, size-zero allocations, and overflow checking;
403 otherwise, other library routines may crash or operate incorrectly.
404 For example, if the replacement
405 .IR free ()
406 does not preserve
407 .IR errno ,
408 then seemingly unrelated library routines may
409 fail without having a valid reason in
410 .IR errno .
411 Private memory allocators may also need to replace other glibc functions;
412 see "Replacing malloc" in the glibc manual for details.
413 .P
414 Crashes in memory allocators
415 are almost always related to heap corruption, such as overflowing
416 an allocated chunk or freeing the same pointer twice.
417 .P
418 The
419 .BR malloc ()
420 implementation is tunable via environment variables;
421 see
422 .BR mallopt (3)
423 for details.
424 .SS Nonportable behavior
425 The behavior of
426 these functions when the requested size is zero
427 is glibc specific;
428 other implementations may return NULL without setting
429 .IR errno ,
430 and portable POSIX programs should tolerate such behavior.
431 See
432 .BR realloc (3p).
433 .P
434 POSIX requires memory allocators
435 to set
436 .I errno
437 upon failure.
438 However, the C standard does not require this, and applications
439 portable to non-POSIX platforms should not assume this.
440 .P
441 Portable programs should not use private memory allocators,
442 as POSIX and the C standard do not allow replacement of
443 .BR malloc (),
444 .BR free (),
445 .BR calloc (),
446 and
447 .BR realloc ().
448 .SH BUGS
449 Programmers would naturally expect by induction that
450 .I \%realloc(p,\~size)
451 is consistent with
452 .I free(p)
453 and
454 .IR malloc(size) ,
455 as that is the behavior in the general case.
456 This is not explicitly required by POSIX.1-2024 or C11,
457 but all conforming implementations are consistent with that.
458 .P
459 The glibc implementation of
460 .BR realloc ()
461 is not consistent with that,
462 and as a consequence,
463 it is dangerous to call
464 .I \%realloc(p,\~0)
465 in glibc.
466 .P
467 A trivial workaround for glibc is calling it as
468 .IR \%realloc(p,\~size?size:1) .
469 .P
470 The workaround for
471 .BR reallocarray ()
472 in glibc
473 \[em]which shares the same bug\[em]
474 would be
475 .IR \%reallocarray(p,\~n?n:1,\~size?size:1) .
476 .SH EXAMPLES
477 .EX
478 #include <err.h>
479 #include <stddef.h>
480 #include <stdio.h>
481 #include <stdlib.h>
482 #include <string.h>
483 \&
484 #define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type)))
485 #define MALLOC(type) MALLOCARRAY(1, type)
486 \&
487 static inline void *my_mallocarray(size_t n, size_t size);
488 \&
489 int
490 main(void)
491 {
492 char *p;
493 \&
494 p = MALLOCARRAY(32, char);
495 if (p == NULL)
496 err(EXIT_FAILURE, "malloc");
497 \&
498 strlcpy(p, "foo", 32);
499 puts(p);
500 }
501 \&
502 static inline void *
503 my_mallocarray(size_t n, size_t size)
504 {
505 return reallocarray(NULL, n, size);
506 }
507 .EE
508 .SH SEE ALSO
509 .\" http://g.oswego.edu/dl/html/malloc.html
510 .\" A Memory Allocator - by Doug Lea
511 .\"
512 .\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html
513 .\" Linux Heap, Contention in free() - David Boreham
514 .\"
515 .\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html
516 .\" malloc() Performance in a Multithreaded Linux Environment -
517 .\" Check Lever, David Boreham
518 .\"
519 .ad l
520 .nh
521 .BR valgrind (1),
522 .BR brk (2),
523 .BR mmap (2),
524 .BR alloca (3),
525 .BR malloc_get_state (3),
526 .BR malloc_info (3),
527 .BR malloc_trim (3),
528 .BR malloc_usable_size (3),
529 .BR mallopt (3),
530 .BR mcheck (3),
531 .BR mtrace (3),
532 .BR posix_memalign (3)
533 .P
534 For details of the GNU C library implementation, see
535 .UR https:\://sourceware.org/glibc/wiki/MallocInternals
536 .UE .