gen/malloc.3

   1 .\" Copyright (c) 2002 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 November 21, 2002
  22 .Dt MALLOC 3
  23 .Os
  24 .Sh NAME
  25 .Nm malloc , calloc , valloc , realloc , reallocf , free , malloc_size , malloc_good_size
  26 .Nd memory allocation
  27 .Sh SYNOPSIS
  28 .In stdlib.h
  29 .Ft void *
  30 .Fn malloc "size_t size"
  31 .Ft void *
  32 .Fn calloc "size_t count" "size_t size"
  33 .Ft void *
  34 .Fn valloc "size_t size"
  35 .Ft void *
  36 .Fn realloc "void *ptr" "size_t size"
  37 .Ft void *
  38 .Fn reallocf "void *ptr" "size_t size"
  39 .Ft void
  40 .Fn free "void *ptr"
  41 .Ft size_t
  42 .Fn malloc_size "void *ptr"
  43 .Ft size_t
  44 .Fn malloc_good_size "size_t size"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn malloc ,
  48 .Fn calloc ,
  49 .Fn valloc ,
  50 .Fn realloc ,
  51 and
  52 .Fn reallocf
  53 functions allocate memory.
  54 The allocated memory is aligned such that it can be used for any data type,
  55 including AltiVec-related types.
  56 The
  57 .Fn free
  58 function frees allocations that were created via the preceding allocation
  59 functions.
  60 The
  61 .Fn malloc_size
  62 and
  63 .Fn malloc_good_size
  64 functions provide information related to the amount of padding space at the end
  65 of allocations.
  66 .Pp
  67 The
  68 .Fn malloc
  69 function allocates
  70 .Fa size
  71 bytes of memory and returns a pointer to the allocated memory.
  72 .Fn malloc
  73 returns a
  74 .Dv NULL
  75 pointer if there is an error.
  76 .Pp
  77 The
  78 .Fn calloc
  79 function contiguously allocates enough space for
  80 .Fa count
  81 objects that are
  82 .Fa size
  83 bytes of memory each and returns a pointer to the allocated memory.
  84 The allocated memory is filled with bytes of value zero.
  85 .Fn calloc
  86 returns a
  87 .Dv NULL
  88 pointer if there is an error.
  89 .Pp
  90 The
  91 .Fn valloc
  92 function allocates
  93 .Fa size
  94 bytes of memory and returns a pointer to the allocated memory.
  95 The allocated memory is aligned on a page boundary.
  96 .Fn valloc
  97 returns a
  98 .Dv NULL
  99 pointer if there is an error.
 100 .Pp
 101 The
 102 .Fn realloc
 103 function tries to change the size of the allocation pointed to by
 104 .Fa ptr
 105 to
 106 .Fa size ,
 107 and return
 108 .Fa ptr .
 109 If there is not enough room to enlarge the memory allocation pointed to by
 110 .Fa ptr ,
 111 .Fn realloc
 112 creates a new allocation, copies as much of the old data pointed to by
 113 .Fa ptr
 114 as will fit to the new allocation, frees the old allocation, and returns a
 115 pointer to the allocated memory.
 116 .Fn realloc
 117 returns a
 118 .Dv NULL
 119 pointer if there is an error, and the allocation pointed to by
 120 .Fa ptr
 121 is still valid.
 122 .Pp
 123 The
 124 .Fn reallocf
 125 function is identical to the
 126 .Fn realloc
 127 function, except that it
 128 will free the passed pointer when the requested memory cannot be allocated.
 129 This is a
 130 .Fx
 131 specific API designed to ease the problems with traditional coding styles
 132 for realloc causing memory leaks in libraries.
 133 .Pp
 134 The
 135 .Fn free
 136 function deallocates the memory allocation pointed to by
 137 .Fa ptr .
 138 .Pp
 139 The
 140 .Fn malloc_size
 141 function
 142 returns the size of the memory block that backs the allocation pointed to by
 143 .Fa ptr .
 144 The memory block size is always at least as large as the allocation it backs,
 145 and may be larger.
 146 .Pp
 147 The
 148 .Fn malloc_good_size
 149 function rounds
 150 .Fa size
 151 up to a value that the allocator implementation can allocate without adding any
 152 padding and returns that rounded up value.
 153 .Sh RETURN VALUES
 154 If successful, the
 155 .Fn malloc ,
 156 .Fn calloc ,
 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 If successful, the
 168 .Fn realloc
 169 and
 170 .Fn reallocf
 171 functions return a pointer to allocated memory.
 172 If there is an error, it returns a
 173 .Dv NULL
 174 pointer and sets
 175 .Va errno
 176 to
 177 .Er ENOMEM .
 178 .Pp
 179 The
 180 .Fn free
 181 function does not return a value.
 182 .Sh DEBUGGING ALLOCATION ERRORS
 183 A number of facilities are provided to aid in debugging allocation errors in
 184 applications.
 185 These facilities are primarily controlled via environment variables.
 186 The recognized environment variables and their meanings are documented below.
 187 .Sh ENVIRONMENT
 188 The following environment variables change the behavior of the
 189 allocation-related functions.
 190 .Bl -tag -width ".Ev MallocStackLoggingNoCompact"
 191 .It Ev MallocLogFile <f>
 192 Create/append messages to the given file path
 193 .Fa <f>
 194 instead of writing to the standard error.
 195 .It Ev MallocGuardEdges
 196 If set, add a guard page before and after each large block.
 197 .It Ev MallocDoNotProtectPrelude
 198 If set, do not add a guard page before large blocks,
 199 even if the
 200 .Ev MallocGuardEdges
 201 environment variable is set.
 202 .It Ev MallocDoNotProtectPostlude
 203 If set, do not add a guard page after large blocks,
 204 even if the
 205 .Ev MallocGuardEdges
 206 environment variable is set.
 207 .It Ev MallocStackLogging
 208 If set, record all stacks, so that tools like
 209 .Nm leaks
 210 can be used.
 211 .It Ev MallocStackLoggingNoCompact
 212 If set, record all stacks in a manner that is compatible with the
 213 .Nm malloc_history
 214 program.
 215 .It Ev MallocPreScribble
 216 If set, fill memory that has been allocated with 0xaa bytes.
 217 This increases the likelihood that a program making assumptions about the
 218 contents of freshly allocated memory will fail.
 219 .It Ev MallocScribble
 220 If set, fill memory that has been deallocated with 0x55 bytes.
 221 This increases the likelihood that a program will fail due to accessing memory
 222 that is no longer allocated.
 223 .It Ev MallocCheckHeapStart <s>
 224 If set, specifies the number of allocations
 225 .Fa <s>
 226 to wait before begining periodic heap checks every
 227 .Fa <n>
 228 as specified by
 229 .Ev MallocCheckHeapEach .
 230 If
 231 .Ev MallocCheckHeapStart
 232 is set but
 233 .Ev MallocCheckHeapEach
 234 is not specified, the default check repetition is 1000.
 235 .It Ev MallocCheckHeapEach <n>
 236 If set, run a consistency check on the heap every
 237 .Fa <n>
 238 operations.
 239 .Ev MallocCheckHeapEach
 240 is only meaningful if
 241 .Ev MallocCheckHeapStart
 242 is also set.
 243 .It Ev MallocCheckHeapSleep <t>
 244 Sets the number of seconds to sleep (waiting for a debugger to attach) when
 245 .Ev MallocCheckHeapStart
 246 is set and a heap corruption is detected.
 247 The default is 100 seconds.
 248 Setting this to zero means not to sleep at all.
 249 Setting this to a negative number means to sleep (for the positive number of
 250 seconds) only the very first time a heap corruption is detected.
 251 .It Ev MallocCheckHeapAbort <b>
 252 When
 253 .Ev MallocCheckHeapStart
 254 is set and this is set to a non-zero value, causes
 255 .Xr abort 3
 256 to be called if a heap corruption is detected, instead of any sleeping.
 257 .It Ev MallocBadFreeAbort <b>
 258 If set to a non-zero value, causes
 259 .Xr abort 3
 260 to be called if the pointer passed to
 261 .Xr free 3
 262 was previously freed, or is otherwise illegal.
 263 .It Ev MallocHelp
 264 If set, print a list of environment variables that are paid heed to by the
 265 allocation-related functions, along with short descriptions.
 266 The list should correspond to this documentation.
 267 .El
 268 .Sh DIAGNOSTIC MESSAGES
 269 .Sh SEE ALSO
 270 .Xr leaks 1 ,
 271 .Xr malloc_history 1 ,
 272 .Xr abort 3
 273 .Pa /Developer/Documentation/ReleaseNotes/DeveloperTools/MallocOptions.html