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 May 23, 2006
  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 .Pp
 132 The
 133 .Fn reallocf
 134 function is identical to the
 135 .Fn realloc
 136 function, except that it
 137 will free the passed pointer when the requested memory cannot be allocated.
 138 This is a
 139 .Fx
 140 specific API designed to ease the problems with traditional coding styles
 141 for realloc causing memory leaks in libraries.
 142 .Pp
 143 The
 144 .Fn free
 145 function deallocates the memory allocation pointed to by
 146 .Fa ptr .
 147 .Sh RETURN VALUES
 148 If successful,
 149 .Fn calloc ,
 150 .Fn malloc ,
 151 .Fn realloc ,
 152 .Fn reallocf ,
 153 and
 154 .Fn valloc
 155 functions return a pointer to allocated memory.
 156 If there is an error, they return a
 157 .Dv NULL
 158 pointer and set
 159 .Va errno
 160 to
 161 .Er ENOMEM .
 162 .Pp
 163 For
 164 .Fn realloc ,
 165 the input pointer is still valid if reallocation failed.
 166 For
 167 .Fn reallocf ,
 168 the input pointer will have been freed if reallocation failed.
 169 .Pp
 170 The
 171 .Fn free
 172 function does not return a value.
 173 .Sh DEBUGGING ALLOCATION ERRORS
 174 A number of facilities are provided to aid in debugging allocation errors in
 175 applications.
 176 These facilities are primarily controlled via environment variables.
 177 The recognized environment variables and their meanings are documented below.
 178 .Sh ENVIRONMENT
 179 The following environment variables change the behavior of the
 180 allocation-related functions.
 181 .Bl -tag -width ".Ev MallocStackLoggingNoCompact"
 182 .It Ev MallocLogFile <f>
 183 Create/append messages to the given file path
 184 .Fa <f>
 185 instead of writing to the standard error.
 186 .It Ev MallocGuardEdges
 187 If set, add a guard page before and after each large block.
 188 .It Ev MallocDoNotProtectPrelude
 189 If set, do not add a guard page before large blocks,
 190 even if the
 191 .Ev MallocGuardEdges
 192 environment variable is set.
 193 .It Ev MallocDoNotProtectPostlude
 194 If set, do not add a guard page after large blocks,
 195 even if the
 196 .Ev MallocGuardEdges
 197 environment variable is set.
 198 .It Ev MallocStackLogging
 199 If set, record all stacks, so that tools like
 200 .Nm leaks
 201 can be used.
 202 .It Ev MallocStackLoggingNoCompact
 203 If set, record all stacks in a manner that is compatible with the
 204 .Nm malloc_history
 205 program.
 206 .It Ev MallocPreScribble
 207 If set, fill memory that has been allocated with 0xaa bytes.
 208 This increases the likelihood that a program making assumptions about the
 209 contents of freshly allocated memory will fail.
 210 .It Ev MallocScribble
 211 If set, fill memory that has been deallocated with 0x55 bytes.
 212 This increases the likelihood that a program will fail due to accessing memory
 213 that is no longer allocated.
 214 .It Ev MallocCheckHeapStart <s>
 215 If set, specifies the number of allocations
 216 .Fa <s>
 217 to wait before begining periodic heap checks every
 218 .Fa <n>
 219 as specified by
 220 .Ev MallocCheckHeapEach .
 221 If
 222 .Ev MallocCheckHeapStart
 223 is set but
 224 .Ev MallocCheckHeapEach
 225 is not specified, the default check repetition is 1000.
 226 .It Ev MallocCheckHeapEach <n>
 227 If set, run a consistency check on the heap every
 228 .Fa <n>
 229 operations.
 230 .Ev MallocCheckHeapEach
 231 is only meaningful if
 232 .Ev MallocCheckHeapStart
 233 is also set.
 234 .It Ev MallocCheckHeapSleep <t>
 235 Sets the number of seconds to sleep (waiting for a debugger to attach) when
 236 .Ev MallocCheckHeapStart
 237 is set and a heap corruption is detected.
 238 The default is 100 seconds.
 239 Setting this to zero means not to sleep at all.
 240 Setting this to a negative number means to sleep (for the positive number of
 241 seconds) only the very first time a heap corruption is detected.
 242 .It Ev MallocCheckHeapAbort <b>
 243 When
 244 .Ev MallocCheckHeapStart
 245 is set and this is set to a non-zero value, causes
 246 .Xr abort 3
 247 to be called if a heap corruption is detected, instead of any sleeping.
 248 .It Ev MallocErrorAbort
 249 If set, causes
 250 .Xr abort 3
 251 to be called if an error was encountered in
 252 .Xr malloc 3
 253 or
 254 .Xr free 3
 255 , such as a calling
 256 .Xr free 3
 257 on a pointer previously freed.
 258 .It Ev MallocHelp
 259 If set, print a list of environment variables that are paid heed to by the
 260 allocation-related functions, along with short descriptions.
 261 The list should correspond to this documentation.
 262 .El
 263 .Sh DIAGNOSTIC MESSAGES
 264 .Sh SEE ALSO
 265 .Xr leaks 1 ,
 266 .Xr malloc_history 1 ,
 267 .Xr abort 3 ,
 268 .Xr malloc_size 3
 269 .Pa /Developer/ADC Reference Library/releasenotes/DeveloperTools/MallocOptions.html