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