lib/libc/stdlib/malloc.3

   1 .\" $NetBSD: malloc.3,v 1.38 2010/05/03 08:23:20 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the American National Standards Committee X3, on Information
   8 .\" Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)malloc.3    8.1 (Berkeley) 6/4/93
  35 .\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
  36 .\"
  37 .Dd May 3, 2010
  38 .Dt MALLOC 3
  39 .Os
  40 .Sh NAME
  41 .Nm malloc , calloc , realloc , free
  42 .Nd general purpose memory allocation functions
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdlib.h
  47 .Ft void *
  48 .Fn malloc "size_t size"
  49 .Ft void *
  50 .Fn calloc "size_t number" "size_t size"
  51 .Ft void *
  52 .Fn realloc "void *ptr" "size_t size"
  53 .Ft void
  54 .Fn free "void *ptr"
  55 .Sh DESCRIPTION
  56 The
  57 .Fn malloc
  58 function allocates
  59 .Fa size
  60 bytes of uninitialized memory.
  61 The allocated space is suitably aligned (after possible pointer coercion)
  62 for storage of any type of object.
  63 .Pp
  64 The
  65 .Fn calloc
  66 function allocates space for
  67 .Fa number
  68 objects,
  69 each
  70 .Fa size
  71 bytes in length.
  72 The result is identical to calling
  73 .Fn malloc
  74 with an argument of
  75 .Dq "number * size" ,
  76 with the exception that the allocated memory is explicitly initialized
  77 to zero bytes.
  78 .Pp
  79 The
  80 .Fn realloc
  81 function changes the size of the previously allocated memory referenced by
  82 .Fa ptr
  83 to
  84 .Fa size
  85 bytes.
  86 The contents of the memory are unchanged up to the lesser of the new and
  87 old sizes.
  88 If the new size is larger,
  89 the value of the newly allocated portion of the memory is undefined.
  90 Upon success, the memory referenced by
  91 .Fa ptr
  92 is freed and a pointer to the newly allocated memory is returned.
  93 Note that
  94 .Fn realloc
  95 may move the memory allocation, resulting in a different return value than
  96 .Fa ptr .
  97 If
  98 .Fa ptr
  99 is
 100 .Dv NULL ,
 101 the
 102 .Fn realloc
 103 function behaves identically to
 104 .Fn malloc
 105 for the specified size.
 106 .Pp
 107 The
 108 .Fn free
 109 function causes the allocated memory referenced by
 110 .Fa ptr
 111 to be made available for future allocations.
 112 If
 113 .Fa ptr
 114 is
 115 .Dv NULL ,
 116 no action occurs.
 117 .Sh RETURN VALUES
 118 The
 119 .Fn malloc
 120 and
 121 .Fn calloc
 122 functions return a pointer to the allocated memory if successful; otherwise
 123 a
 124 .Dv NULL
 125 pointer is returned and
 126 .Va errno
 127 is set to
 128 .Er ENOMEM .
 129 .Pp
 130 The
 131 .Fn realloc
 132 function returns a pointer, possibly identical to
 133 .Fa ptr ,
 134 to the allocated memory
 135 if successful; otherwise a
 136 .Dv NULL
 137 pointer is returned, and
 138 .Va errno
 139 is set to
 140 .Er ENOMEM
 141 if the error was the result of an allocation failure.
 142 The
 143 .Fn realloc
 144 function always leaves the original buffer intact
 145 when an error occurs.
 146 .Pp
 147 The
 148 .Fn free
 149 function returns no value.
 150 .Sh EXAMPLES
 151 When using
 152 .Fn malloc ,
 153 be careful to avoid the following idiom:
 154 .Bd -literal -offset indent
 155 if ((p = malloc(number * size)) == NULL)
 156         err(EXIT_FAILURE, "malloc");
 157 .Ed
 158 .Pp
 159 The multiplication may lead to an integer overflow.
 160 To avoid this,
 161 .Fn calloc
 162 is recommended.
 163 .Pp
 164 If
 165 .Fn malloc
 166 must be used, be sure to test for overflow:
 167 .Bd -literal -offset indent
 168 if (size && number > SIZE_MAX / size) {
 169         errno = EOVERFLOW;
 170         err(EXIT_FAILURE, "allocation");
 171 }
 172 .Ed
 173 .Pp
 174 When using
 175 .Fn realloc ,
 176 one must be careful to avoid the following idiom:
 177 .Pp
 178 .Bd -literal -offset indent
 179 nsize += 50;
 180
 181 if ((p = realloc(p, nsize)) == NULL)
 182         return NULL;
 183 .Ed
 184 .Pp
 185 Do not adjust the variable describing how much memory has been allocated
 186 until it is known that the allocation has been successful.
 187 This can cause aberrant program behavior if the incorrect size value is used.
 188 In most cases, the above example will also leak memory.
 189 As stated earlier, a return value of
 190 .Dv NULL
 191 indicates that the old object still remains allocated.
 192 Better code looks like this:
 193 .Bd -literal -offset indent
 194 newsize = size + 50;
 195
 196 if ((p2 = realloc(p, newsize)) == NULL) {
 197
 198         if (p != NULL)
 199                 free(p);
 200
 201         p = NULL;
 202         return NULL;
 203 }
 204
 205 p = p2;
 206 size = newsize;
 207 .Ed
 208 .Sh SEE ALSO
 209 .\" .Xr limits 1 ,
 210 .Xr madvise 2 ,
 211 .Xr mmap 2 ,
 212 .Xr sbrk 2 ,
 213 .Xr alloca 3 ,
 214 .Xr atexit 3 ,
 215 .Xr getpagesize 3 ,
 216 .Xr memory 3 ,
 217 .Xr posix_memalign 3
 218 .Pp
 219 For the implementation details, see
 220 .Xr jemalloc 3 .
 221 .Sh STANDARDS
 222 The
 223 .Fn malloc ,
 224 .Fn calloc ,
 225 .Fn realloc
 226 and
 227 .Fn free
 228 functions conform to
 229 .St -isoC .