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