[apple/libc.git] / gen / malloc_zone_malloc.3

.\" Copyright (c) 2008 Apple, Inc.  All rights reserved.
.\"
.\" @APPLE_LICENSE_HEADER_START@
.\"
.\" The contents of this file constitute Original Code as defined in and
.\" are subject to the Apple Public Source License Version 1.1 (the
.\" "License").  You may not use this file except in compliance with the
.\" License.  Please obtain a copy of the License at
.\" http://www.apple.com/publicsource and read it before using this file.
.\"
.\" This Original Code and all software distributed under the License are
.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
.\" License for the specific language governing rights and limitations
.\" under the License.
.\"
.\" @APPLE_LICENSE_HEADER_END@
.\"
.Dd Aug 13, 2008
.Dt MALLOC_ZONE_MALLOC 3
.Os
.Sh NAME
.Nm malloc_create_zone ,
.Nm malloc_destroy_zone ,
.Nm malloc_default_zone ,
.Nm malloc_zone_from_ptr ,
.Nm malloc_zone_malloc ,
.Nm malloc_zone_calloc ,
.Nm malloc_zone_valloc ,
.Nm malloc_zone_realloc ,
.Nm malloc_zone_memalign ,
.Nm malloc_zone_free
.Nd zone-based memory allocation
.Sh SYNOPSIS
.In malloc/malloc.h
.Ft malloc_zone_t *
.Fo malloc_create_zone
.Fa "vm_size_t start_size"
.Fa "unsigned flags"
.Fc
.Ft void
.Fo malloc_destroy_zone
.Fa "malloc_zone_t *zone"
.Fc
.Ft malloc_zone_t *
.Fo malloc_default_zone
.Fa void
.Fc
.Ft malloc_zone_t *
.Fo malloc_zone_from_ptr
.Fa "const void *ptr"
.Fc
.Ft void *
.Fo malloc_zone_malloc
.Fa "malloc_zone_t *zone"
.Fa "size_t size"
.Fc
.Ft void *
.Fo malloc_zone_calloc
.Fa "malloc_zone_t *zone"
.Fa "size_t num_items"
.Fa "size_t size"
.Fc
.Ft void *
.Fo malloc_zone_valloc
.Fa "malloc_zone_t *zone"
.Fa "size_t size"
.Fc
.Ft void *
.Fo malloc_zone_realloc
.Fa "malloc_zone_t *zone"
.Fa "void *ptr"
.Fa "size_t size"
.Fc
.Ft void *
.Fo malloc_zone_memalign
.Fa "malloc_zone_t *zone"
.Fa "size_t alignment"
.Fa "size_t size"
.Fc
.Ft void
.Fo malloc_zone_free
.Fa "malloc_zone_t *zone"
.Fa "void *ptr"
.Fc
.Sh DESCRIPTION
The
.Fn malloc_create_zone
function creates a malloc zone, advising an initial allocation of
.Fa start_size
bytes, and specifying 
.Fa flags
that alter the standard behavior of the zone.
The returned malloc zone can be used to provide custom allocation and 
deallocation behavior, and to retrieve additional information about the
allocations in that zone.
.Pp
The
.Fn malloc_destroy_zone
function deallocates all memory associated with objects in 
.Fa zone
as well as 
.Fa zone
itself.
.Pp
The
.Fn malloc_default_zone
function returns the default system malloc zone, used by
.Xr malloc 3 ,
and
.Xr free 3 .
.Pp
The
.Fn malloc_zone_from_ptr
function returns a pointer to the malloc zone which contains
.Fa ptr
or NULL, if the pointer does not point to an allocated object in any current
malloc zone.
.Pp
The
.Fn malloc_zone_malloc ,
.Fn malloc_zone_calloc ,
.Fn malloc_zone_valloc ,
.Fn malloc_zone_realloc ,
.Fn malloc_zone_memalign ,
and
.Fn malloc_zone_free
perform the same task on
.Fa zone
as their non-prefixed variants, 
.Xr malloc 3 ,
.Xr calloc 3 ,
.Xr valloc 3 ,
.Xr realloc 3 ,
.Xr posix_memalign 3 ,
and 
.Xr free 3 perform on the default system malloc zone.
.Sh RETURN VALUES
The 
.Fn malloc_create_zone ,
.Fn malloc_default_zone ,
and
.Fn malloc_zone_from_ptr
functions return a pointer to a malloc_zone_t structure, or NULL if there was
an error.
.Pp
The 
.Fn malloc_zone_malloc ,
.Fn malloc_zone_calloc ,
.Fn malloc_zone_valloc ,
.Fn malloc_zone_realloc ,
and
.Fn malloc_zone_memalign
functions return a pointer to allocated memory.  If there is an error, they 
return a NULL pointer.  They are not required to set 
.Va errno .
.El
.Sh SEE ALSO
.Xr malloc 3 ,
.Xr posix_memalign 3
Commit	Line	Data
34e8f829 A	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