gen/malloc.3

   1 .\" Copyright (c) 2006 Apple Computer, Inc.  All rights reserved.
   2 .\"
   3 .\" @APPLE_LICENSE_HEADER_START@
   4 .\"
   5 .\" The contents of this file constitute Original Code as defined in and
   6 .\" are subject to the Apple Public Source License Version 1.1 (the
   7 .\" "License").  You may not use this file except in compliance with the
   8 .\" License.  Please obtain a copy of the License at
   9 .\" http://www.apple.com/publicsource and read it before using this file.
  10 .\"
  11 .\" This Original Code and all software distributed under the License are
  12 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  13 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  14 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  15 .\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  16 .\" License for the specific language governing rights and limitations
  17 .\" under the License.
  18 .\"
  19 .\" @APPLE_LICENSE_HEADER_END@
  20 .\"
  21 .Dd Aug 13, 2008
  22 .Dt MALLOC 3
  23 .Os
  24 .Sh NAME
  25 .Nm calloc ,
  26 .Nm free ,
  27 .Nm malloc ,
  28 .Nm realloc ,
  29 .Nm reallocf ,
  30 .Nm valloc
  31 .Nd memory allocation
  32 .Sh SYNOPSIS
  33 .In stdlib.h
  34 .Ft void *
  35 .Fo calloc
  36 .Fa "size_t count"
  37 .Fa "size_t size"
  38 .Fc
  39 .Ft void
  40 .Fo free
  41 .Fa "void *ptr"
  42 .Fc
  43 .Ft void *
  44 .Fo malloc
  45 .Fa "size_t size"
  46 .Fc
  47 .Ft void *
  48 .Fo realloc
  49 .Fa "void *ptr"
  50 .Fa "size_t size"
  51 .Fc
  52 .Ft void *
  53 .Fo reallocf
  54 .Fa "void *ptr"
  55 .Fa "size_t size"
  56 .Fc
  57 .Ft void *
  58 .Fo valloc
  59 .Fa "size_t size"
  60 .Fc
  61 .Sh DESCRIPTION
  62 The
  63 .Fn malloc ,
  64 .Fn calloc ,
  65 .Fn valloc ,
  66 .Fn realloc ,
  67 and
  68 .Fn reallocf
  69 functions allocate memory.
  70 The allocated memory is aligned such that it can be used for any data type,
  71 including AltiVec- and SSE-related types.
  72 The
  73 .Fn free
  74 function frees allocations that were created via the preceding allocation
  75 functions.
  76 .Pp
  77 The
  78 .Fn malloc
  79 function allocates
  80 .Fa size
  81 bytes of memory and returns a pointer to the allocated memory.
  82 .Pp
  83 The
  84 .Fn calloc
  85 function contiguously allocates enough space for
  86 .Fa count
  87 objects that are
  88 .Fa size
  89 bytes of memory each and returns a pointer to the allocated memory.
  90 The allocated memory is filled with bytes of value zero.
  91 .Pp
  92 The
  93 .Fn valloc
  94 function allocates
  95 .Fa size
  96 bytes of memory and returns a pointer to the allocated memory.
  97 The allocated memory is aligned on a page boundary.
  98 .Pp
  99 The
 100 .Fn realloc
 101 function tries to change the size of the allocation pointed to by
 102 .Fa ptr
 103 to
 104 .Fa size ,
 105 and returns
 106 .Fa ptr .
 107 If there is not enough room to enlarge the memory allocation pointed to by
 108 .Fa ptr ,
 109 .Fn realloc
 110 creates a new allocation, copies as much of the old data pointed to by
 111 .Fa ptr
 112 as will fit to the new allocation, frees the old allocation, and returns a
 113 pointer to the allocated memory.
 114 If
 115 .Fa ptr
 116 is
 117 .Dv NULL ,
 118 .Fn realloc
 119 is identical to a call to
 120 .Fn malloc
 121 for
 122 .Fa size
 123 bytes.
 124 If
 125 .Fa size
 126 is zero and
 127 .Fa ptr
 128 is not
 129 .Dv NULL ,
 130 a new, minimum sized object is allocated and the original object is freed.
 131 When extending a region allocated with calloc(3), realloc(3) does not guarantee
 132 that the additional memory is also zero-filled.
 133 .Pp
 134 The
 135 .Fn reallocf
 136 function is identical to the
 137 .Fn realloc
 138 function, except that it
 139 will free the passed pointer when the requested memory cannot be allocated.
 140 This is a
 141 .Fx
 142 specific API designed to ease the problems with traditional coding styles
 143 for realloc causing memory leaks in libraries.
 144 .Pp
 145 The
 146 .Fn free
 147 function deallocates the memory allocation pointed to by
 148 .Fa ptr .  If
 149 .Fa ptr
 150 is a NULL pointer, no operation is performed.
 151 .Sh RETURN VALUES
 152 If successful,
 153 .Fn calloc ,
 154 .Fn malloc ,
 155 .Fn realloc ,
 156 .Fn reallocf ,
 157 and
 158 .Fn valloc
 159 functions return a pointer to allocated memory.
 160 If there is an error, they return a
 161 .Dv NULL
 162 pointer and set
 163 .Va errno
 164 to
 165 .Er ENOMEM .
 166 .Pp
 167 For
 168 .Fn realloc ,
 169 the input pointer is still valid if reallocation failed.
 170 For
 171 .Fn reallocf ,
 172 the input pointer will have been freed if reallocation failed.
 173 .Pp
 174 The
 175 .Fn free
 176 function does not return a value.
 177 .Sh DEBUGGING ALLOCATION ERRORS
 178 A number of facilities are provided to aid in debugging allocation errors in
 179 applications.
 180 These facilities are primarily controlled via environment variables.
 181 The recognized environment variables and their meanings are documented below.
 182 .Sh ENVIRONMENT
 183 The following environment variables change the behavior of the
 184 allocation-related functions.
 185 .Bl -tag -width ".Ev MallocStackLoggingNoCompact"
 186 .It Ev MallocLogFile <f>
 187 Create/append messages to the given file path
 188 .Fa <f>
 189 instead of writing to the standard error.
 190 .It Ev MallocGuardEdges
 191 If set, add a guard page before and after each large block.
 192 .It Ev MallocDoNotProtectPrelude
 193 If set, do not add a guard page before large blocks,
 194 even if the
 195 .Ev MallocGuardEdges
 196 environment variable is set.
 197 .It Ev MallocDoNotProtectPostlude
 198 If set, do not add a guard page after large blocks,
 199 even if the
 200 .Ev MallocGuardEdges
 201 environment variable is set.
 202 .It Ev MallocStackLogging
 203 If set, record all stacks, so that tools like
 204 .Nm leaks
 205 can be used.
 206 .It Ev MallocStackLoggingNoCompact
 207 If set, record all stacks in a manner that is compatible with the
 208 .Nm malloc_history
 209 program.
 210 .It Ev MallocStackLoggingDirectory
 211 If set, records stack logs to the directory specified instead of saving them to the default location (/tmp).
 212 .It Ev MallocScribble
 213 If set, fill memory that has been allocated with 0xaa bytes.
 214 This increases the likelihood that a program making assumptions about the contents of
 215 freshly allocated memory will fail.
 216 Also if set, fill memory that has been deallocated with 0x55 bytes.
 217 This increases the likelihood that a program will fail due to accessing memory
 218 that is no longer allocated.
 219 .It Ev MallocCheckHeapStart <s>
 220 If set, specifies the number of allocations
 221 .Fa <s>
 222 to wait before begining periodic heap checks every
 223 .Fa <n>
 224 as specified by
 225 .Ev MallocCheckHeapEach .
 226 If
 227 .Ev MallocCheckHeapStart
 228 is set but
 229 .Ev MallocCheckHeapEach
 230 is not specified, the default check repetition is 1000.
 231 .It Ev MallocCheckHeapEach <n>
 232 If set, run a consistency check on the heap every
 233 .Fa <n>
 234 operations.
 235 .Ev MallocCheckHeapEach
 236 is only meaningful if
 237 .Ev MallocCheckHeapStart
 238 is also set.
 239 .It Ev MallocCheckHeapSleep <t>
 240 Sets the number of seconds to sleep (waiting for a debugger to attach) when
 241 .Ev MallocCheckHeapStart
 242 is set and a heap corruption is detected.
 243 The default is 100 seconds.
 244 Setting this to zero means not to sleep at all.
 245 Setting this to a negative number means to sleep (for the positive number of
 246 seconds) only the very first time a heap corruption is detected.
 247 .It Ev MallocCheckHeapAbort <b>
 248 When
 249 .Ev MallocCheckHeapStart
 250 is set and this is set to a non-zero value, causes
 251 .Xr abort 3
 252 to be called if a heap corruption is detected, instead of any sleeping.
 253 .It Ev MallocErrorAbort
 254 If set, causes
 255 .Xr abort 3
 256 to be called if an error was encountered in
 257 .Xr malloc 3
 258 or
 259 .Xr free 3
 260 , such as a calling
 261 .Xr free 3
 262 on a pointer previously freed.
 263 .It Ev MallocCorruptionAbort
 264 Similar to
 265 .Ev
 266 MallocErrorAbort
 267 but will not abort in out of memory conditions, making it more useful to catch
 268 only those errors which will cause memory corruption.
 269 MallocCorruptionAbort is always set on 64-bit processes.
 270 .It Ev MallocHelp
 271 If set, print a list of environment variables that are paid heed to by the
 272 allocation-related functions, along with short descriptions.
 273 The list should correspond to this documentation.
 274 .El
 275 .Sh DIAGNOSTIC MESSAGES
 276 .Sh SEE ALSO
 277 .Xr leaks 1 ,
 278 .Xr malloc_history 1 ,
 279 .Xr abort 3 ,
 280 .Xr malloc_size 3 ,
 281 .Xr malloc_zone_malloc 3 ,
 282 .Xr posix_memalign 3 ,
 283 .Xr libgmalloc 3