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 The returned malloc zone can be used to provide custom allocation and
  96 deallocation behavior, and to retrieve additional information about the
  97 allocations in that zone.
  98 At present there are no client settable flag values recognized by malloc_create_zone(),
  99 the flags argument should always be passed as zero.
 100 .Pp
 101 The
 102 .Fn malloc_destroy_zone
 103 function deallocates all memory associated with objects in
 104 .Fa zone
 105 as well as
 106 .Fa zone
 107 itself.
 108 .Pp
 109 The
 110 .Fn malloc_default_zone
 111 function returns the default system malloc zone, used by
 112 .Xr malloc 3 ,
 113 and
 114 .Xr free 3 .
 115 .Pp
 116 The
 117 .Fn malloc_zone_from_ptr
 118 function returns a pointer to the malloc zone which contains
 119 .Fa ptr
 120 or NULL, if the pointer does not point to an allocated object in any current
 121 malloc zone.
 122 .Pp
 123 The
 124 .Fn malloc_zone_malloc ,
 125 .Fn malloc_zone_calloc ,
 126 .Fn malloc_zone_valloc ,
 127 .Fn malloc_zone_realloc ,
 128 .Fn malloc_zone_memalign ,
 129 and
 130 .Fn malloc_zone_free
 131 perform the same task on
 132 .Fa zone
 133 as their non-prefixed variants,
 134 .Xr malloc 3 ,
 135 .Xr calloc 3 ,
 136 .Xr valloc 3 ,
 137 .Xr realloc 3 ,
 138 .Xr posix_memalign 3 ,
 139 and
 140 .Xr free 3 perform on the default system malloc zone.
 141 .Sh RETURN VALUES
 142 The
 143 .Fn malloc_create_zone ,
 144 .Fn malloc_default_zone ,
 145 and
 146 .Fn malloc_zone_from_ptr
 147 functions return a pointer to a malloc_zone_t structure, or NULL if there was
 148 an error.
 149 .Pp
 150 The
 151 .Fn malloc_zone_malloc ,
 152 .Fn malloc_zone_calloc ,
 153 .Fn malloc_zone_valloc ,
 154 .Fn malloc_zone_realloc ,
 155 and
 156 .Fn malloc_zone_memalign
 157 functions return a pointer to allocated memory.  If there is an error, they
 158 return a NULL pointer.  They are not required to set
 159 .Va errno .
 160 .El
 161 .Sh SEE ALSO
 162 .Xr malloc 3 ,
 163 .Xr posix_memalign 3