gen/malloc_zone_malloc.3

   1 .\" Copyright (c) 2008 Apple, 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_ZONE_MALLOC 3
  23 .Os
  24 .Sh NAME
  25 .Nm malloc_create_zone ,
  26 .Nm malloc_destroy_zone ,
  27 .Nm malloc_default_zone ,
  28 .Nm malloc_zone_from_ptr ,
  29 .Nm malloc_zone_malloc ,
  30 .Nm malloc_zone_calloc ,
  31 .Nm malloc_zone_valloc ,
  32 .Nm malloc_zone_realloc ,
  33 .Nm malloc_zone_memalign ,
  34 .Nm malloc_zone_free
  35 .Nd zone-based memory allocation
  36 .Sh SYNOPSIS
  37 .In malloc/malloc.h
  38 .Ft malloc_zone_t *
  39 .Fo malloc_create_zone
  40 .Fa "vm_size_t start_size"
  41 .Fa "unsigned flags"
  42 .Fc
  43 .Ft void
  44 .Fo malloc_destroy_zone
  45 .Fa "malloc_zone_t *zone"
  46 .Fc
  47 .Ft malloc_zone_t *
  48 .Fo malloc_default_zone
  49 .Fa void
  50 .Fc
  51 .Ft malloc_zone_t *
  52 .Fo malloc_zone_from_ptr
  53 .Fa "const void *ptr"
  54 .Fc
  55 .Ft void *
  56 .Fo malloc_zone_malloc
  57 .Fa "malloc_zone_t *zone"
  58 .Fa "size_t size"
  59 .Fc
  60 .Ft void *
  61 .Fo malloc_zone_calloc
  62 .Fa "malloc_zone_t *zone"
  63 .Fa "size_t num_items"
  64 .Fa "size_t size"
  65 .Fc
  66 .Ft void *
  67 .Fo malloc_zone_valloc
  68 .Fa "malloc_zone_t *zone"
  69 .Fa "size_t size"
  70 .Fc
  71 .Ft void *
  72 .Fo malloc_zone_realloc
  73 .Fa "malloc_zone_t *zone"
  74 .Fa "void *ptr"
  75 .Fa "size_t size"
  76 .Fc
  77 .Ft void *
  78 .Fo malloc_zone_memalign
  79 .Fa "malloc_zone_t *zone"
  80 .Fa "size_t alignment"
  81 .Fa "size_t size"
  82 .Fc
  83 .Ft void
  84 .Fo malloc_zone_free
  85 .Fa "malloc_zone_t *zone"
  86 .Fa "void *ptr"
  87 .Fc
  88 .Sh DESCRIPTION
  89 The
  90 .Fn malloc_create_zone
  91 function creates a malloc zone, advising an initial allocation of
  92 .Fa start_size
  93 bytes, and specifying
  94 .Fa flags
  95 that alter the standard behavior of the zone.
  96 The returned malloc zone can be used to provide custom allocation and
  97 deallocation behavior, and to retrieve additional information about the
  98 allocations in that zone.
  99 .Pp
 100 The
 101 .Fn malloc_destroy_zone
 102 function deallocates all memory associated with objects in
 103 .Fa zone
 104 as well as
 105 .Fa zone
 106 itself.
 107 .Pp
 108 The
 109 .Fn malloc_default_zone
 110 function returns the default system malloc zone, used by
 111 .Xr malloc 3 ,
 112 and
 113 .Xr free 3 .
 114 .Pp
 115 The
 116 .Fn malloc_zone_from_ptr
 117 function returns a pointer to the malloc zone which contains
 118 .Fa ptr
 119 or NULL, if the pointer does not point to an allocated object in any current
 120 malloc zone.
 121 .Pp
 122 The
 123 .Fn malloc_zone_malloc ,
 124 .Fn malloc_zone_calloc ,
 125 .Fn malloc_zone_valloc ,
 126 .Fn malloc_zone_realloc ,
 127 .Fn malloc_zone_memalign ,
 128 and
 129 .Fn malloc_zone_free
 130 perform the same task on
 131 .Fa zone
 132 as their non-prefixed variants,
 133 .Xr malloc 3 ,
 134 .Xr calloc 3 ,
 135 .Xr valloc 3 ,
 136 .Xr realloc 3 ,
 137 .Xr posix_memalign 3 ,
 138 and
 139 .Xr free 3 perform on the default system malloc zone.
 140 .Sh RETURN VALUES
 141 The
 142 .Fn malloc_create_zone ,
 143 .Fn malloc_default_zone ,
 144 and
 145 .Fn malloc_zone_from_ptr
 146 functions return a pointer to a malloc_zone_t structure, or NULL if there was
 147 an error.
 148 .Pp
 149 The
 150 .Fn malloc_zone_malloc ,
 151 .Fn malloc_zone_calloc ,
 152 .Fn malloc_zone_valloc ,
 153 .Fn malloc_zone_realloc ,
 154 and
 155 .Fn malloc_zone_memalign
 156 functions return a pointer to allocated memory.  If there is an error, they
 157 return a NULL pointer.  They are not required to set
 158 .Va errno .
 159 .El
 160 .Sh SEE ALSO
 161 .Xr malloc 3 ,
 162 .Xr posix_memalign 3