man3/malloc.3

   1 .\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\" License.
  23 .\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu)
  24 .\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701
  25 .\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de)
  26 .\"
  27 .TH MALLOC 3  2007-06-25 "GNU" "Linux Programmer's Manual"
  28 .SH NAME
  29 calloc, malloc, free, realloc \- Allocate and free dynamic memory
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <stdlib.h>
  33 .sp
  34 .BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
  35 .br
  36 .BI "void *malloc(size_t " "size" );
  37 .br
  38 .BI "void free(void " "*ptr" );
  39 .br
  40 .BI "void *realloc(void " "*ptr" ", size_t "  "size" );
  41 .fi
  42 .SH DESCRIPTION
  43 .BR calloc ()
  44 allocates memory for an array of
  45 .I nmemb
  46 elements of
  47 .I size
  48 bytes each and returns a pointer to the allocated memory.
  49 The memory is set to zero.
  50 .PP
  51 .BR malloc ()
  52 allocates
  53 .I size
  54 bytes and returns a pointer to the allocated memory.
  55 The memory is not cleared.
  56 .PP
  57 .BR free ()
  58 frees the memory space pointed to by
  59 .IR ptr ,
  60 which must have been returned by a previous call to
  61 .BR malloc (),
  62 .BR calloc ()
  63 or
  64 .BR realloc ().
  65 Otherwise, or if
  66 .BI "free(" "ptr" )
  67 has already been called before, undefined behavior occurs.
  68 If
  69 .I ptr
  70 is NULL, no operation is performed.
  71 .PP
  72 .BR realloc ()
  73 changes the size of the memory block pointed to by
  74 .I ptr
  75 to
  76 .I size
  77 bytes.
  78 The contents will be unchanged to the minimum of the old and new sizes;
  79 newly allocated memory will be uninitialized.
  80 If
  81 .I ptr
  82 is NULL, the call is equivalent to
  83 .IR malloc(size) ;
  84 if
  85 .I size
  86 is equal to zero,
  87 the call is equivalent to
  88 .BI "free(" "ptr" ) .
  89 Unless
  90 .I ptr
  91 is NULL, it must have been returned by an earlier call to
  92 .BR malloc (),
  93 .BR calloc ()
  94 or
  95 .BR realloc ().
  96 If the area pointed to was moved, a
  97 .BI "free(" "ptr" )
  98 is done.
  99 .SH "RETURN VALUE"
 100 For
 101 .BR calloc ()
 102 and
 103 .BR malloc (),
 104 the value returned is a pointer to the allocated memory, which is suitably
 105 aligned for any kind of variable, or NULL if the request fails.
 106 .PP
 107 .BR free ()
 108 returns no value.
 109 .PP
 110 .BR realloc ()
 111 returns a pointer to the newly allocated memory, which is suitably
 112 aligned for any kind of variable and may be different from
 113 .IR ptr ,
 114 or NULL if the request fails.
 115 If
 116 .I size
 117 was equal to 0, either NULL or a pointer suitable to be passed to
 118 .BR free ()
 119 is returned.
 120 If
 121 .BR realloc ()
 122 fails the original block is left untouched; it is not freed or moved.
 123 .SH "CONFORMING TO"
 124 C89, C99.
 125 .SH NOTES
 126 The Unix98 standard requires
 127 .BR malloc (),
 128 .BR calloc (),
 129 and
 130 .BR realloc ()
 131 to set
 132 .I errno
 133 to ENOMEM upon failure.
 134 Glibc assumes that this is done
 135 (and the glibc versions of these routines do this); if you
 136 use a private malloc implementation that does not set
 137 .IR errno ,
 138 then certain library routines may fail without having
 139 a reason in
 140 .IR errno .
 141 .LP
 142 Crashes in
 143 .BR malloc (),
 144 .BR calloc (),
 145 .BR realloc (),
 146 or
 147 .BR free ()
 148 are almost always related to heap corruption, such as overflowing
 149 an allocated chunk or freeing the same pointer twice.
 150 .PP
 151 Recent versions of Linux libc (later than 5.4.23) and GNU libc (2.x)
 152 include a malloc implementation which is tunable via environment
 153 variables.
 154 When
 155 .BR MALLOC_CHECK_
 156 is set, a special (less efficient) implementation is used which
 157 is designed to be tolerant against simple errors, such as double
 158 calls of
 159 .BR free ()
 160 with the same argument, or overruns of a single byte (off-by-one
 161 bugs).
 162 Not all such errors can be protected against, however, and
 163 memory leaks can result.
 164 If
 165 .BR MALLOC_CHECK_
 166 is set to 0, any detected heap corruption is silently ignored;
 167 if set to 1, a diagnostic message is printed on \fIstderr\fP;
 168 if set to 2,
 169 .BR abort (3)
 170 is called immediately;
 171 if set to 3, a diagnostic message is printed on \fIstderr\fP
 172 and the program is aborted.
 173 Using a non-zero
 174 .B MALLOC_CHECK_
 175 value can be useful because otherwise
 176 a crash may happen much later, and the true cause for the problem
 177 is then very hard to track down.
 178 .SH BUGS
 179 By default, Linux follows an optimistic memory allocation strategy.
 180 This means that when
 181 .BR malloc ()
 182 returns non-NULL there is no guarantee that the memory really
 183 is available.
 184 This is a really bad bug.
 185 In case it turns out that the system is out of memory,
 186 one or more processes will be killed by the infamous OOM killer.
 187 In case Linux is employed under circumstances where it would be
 188 less desirable to suddenly lose some randomly picked processes,
 189 and moreover the kernel version is sufficiently recent,
 190 one can switch off this overcommitting behavior using a command like:
 191 .in +0.5i
 192 .nf
 193
 194 # echo 2 > /proc/sys/vm/overcommit_memory
 195
 196 .fi
 197 .in
 198 See also the kernel Documentation directory, files
 199 .I vm/overcommit-accounting
 200 and
 201 .IR sysctl/vm.txt .
 202 .SH "SEE ALSO"
 203 .BR brk (2),
 204 .BR posix_memalign (3)