1MALLOC(3) Linux Programmer's Manual MALLOC(3)
2
6 calloc, malloc, free, realloc - Allocate and free dynamic memory
7
9 #include <stdlib.h>
10 void *calloc(size_t nmemb, size_t size);
12 void *malloc(size_t size);
13 void free(void *ptr);
14 void *realloc(void *ptr, size_t size);
15
17 calloc() allocates memory for an array of nmemb elements of size bytes
18 each and returns a pointer to the allocated memory. The memory is set
19 to zero. If nmemb or size is 0, then calloc() returns either NULL, or
20 a unique pointer value that can later be successfully passed to free().
21 malloc() allocates size bytes and returns a pointer to the allocated
23 memory. The memory is not cleared. If size is 0, then malloc()
24 returns either NULL, or a unique pointer value that can later be suc‐
25 cessfully passed to free().
26 free() frees the memory space pointed to by ptr, which must have been
28 returned by a previous call to malloc(), calloc() or realloc(). Other‐
29 wise, or if free(ptr) has already been called before, undefined behav‐
30 ior occurs. If ptr is NULL, no operation is performed.
31 realloc() changes the size of the memory block pointed to by ptr to
33 size bytes. The contents will be unchanged to the minimum of the old
34 and new sizes; newly allocated memory will be uninitialized. If ptr is
35 NULL, then the call is equivalent to malloc(size), for all values of
36 size; if size is equal to zero, and ptr is not NULL, then the call is
37 equivalent to free(ptr). Unless ptr is NULL, it must have been
38 returned by an earlier call to malloc(), calloc() or realloc(). If the
39 area pointed to was moved, a free(ptr) is done.
40
42 For calloc() and malloc(), return a pointer to the allocated memory,
43 which is suitably aligned for any kind of variable. On error, these
44 functions return NULL. NULL may also be returned by a successful call
45 to malloc() with a size of zero, or by a successful call to calloc()
46 with nmemb or size equal to zero.
47 free() returns no value.
49 realloc() returns a pointer to the newly allocated memory, which is
51 suitably aligned for any kind of variable and may be different from
52 ptr, or NULL if the request fails. If size was equal to 0, either NULL
53 or a pointer suitable to be passed to free() is returned. If realloc()
54 fails the original block is left untouched; it is not freed or moved.
55
57 C89, C99.
58
60 Normally, malloc() allocates memory from the heap, and adjusts the size
61 of the heap as required, using sbrk(2). When allocating blocks of mem‐
62 ory larger than MMAP_THRESHOLD bytes, the glibc malloc() implementation
63 allocates the memory as a private anonymous mapping using mmap(2).
64 MMAP_THRESHOLD is 128 kB by default, but is adjustable using mal‐
65 lopt(3). Allocations performed using mmap(2) are unaffected by the
66 RLIMIT_DATA resource limit (see getrlimit(2)).
67 The Unix98 standard requires malloc(), calloc(), and realloc() to set
69 errno to ENOMEM upon failure. Glibc assumes that this is done (and the
70 glibc versions of these routines do this); if you use a private malloc
71 implementation that does not set errno, then certain library routines
72 may fail without having a reason in errno.
73 Crashes in malloc(), calloc(), realloc(), or free() are almost always
75 related to heap corruption, such as overflowing an allocated chunk or
76 freeing the same pointer twice.
77 Recent versions of Linux libc (later than 5.4.23) and glibc (2.x)
79 include a malloc() implementation which is tunable via environment
80 variables. When MALLOC_CHECK_ is set, a special (less efficient)
81 implementation is used which is designed to be tolerant against simple
82 errors, such as double calls of free() with the same argument, or over‐
83 runs of a single byte (off-by-one bugs). Not all such errors can be
84 protected against, however, and memory leaks can result. If MAL‐
85 LOC_CHECK_ is set to 0, any detected heap corruption is silently
86 ignored; if set to 1, a diagnostic message is printed on stderr; if set
87 to 2, abort(3) is called immediately; if set to 3, a diagnostic message
88 is printed on stderr and the program is aborted. Using a non-zero MAL‐
89 LOC_CHECK_ value can be useful because otherwise a crash may happen
90 much later, and the true cause for the problem is then very hard to
91 track down.
92
94 By default, Linux follows an optimistic memory allocation strategy.
95 This means that when malloc() returns non-NULL there is no guarantee
96 that the memory really is available. This is a really bad bug. In
97 case it turns out that the system is out of memory, one or more pro‐
98 cesses will be killed by the infamous OOM killer. In case Linux is
99 employed under circumstances where it would be less desirable to sud‐
100 denly lose some randomly picked processes, and moreover the kernel ver‐
101 sion is sufficiently recent, one can switch off this overcommitting
102 behavior using a command like:
103 # echo 2 > /proc/sys/vm/overcommit_memory
105 See also the kernel Documentation directory, files vm/overcommit-
107 accounting and sysctl/vm.txt.
108
110 brk(2), mmap(2), alloca(3), posix_memalign(3)
111
113 This page is part of release 3.22 of the Linux man-pages project. A
114 description of the project, and information about reporting bugs, can
115 be found at http://www.kernel.org/doc/man-pages/.
116GNU 2009-01-13 MALLOC(3)