malloc.3: Remove a ,
[dragonfly.git] / lib / libc / stdlib / malloc.3
CommitLineData
899b08f0
SW
1.\" $NetBSD: malloc.3,v 1.38 2010/05/03 08:23:20 jruoho Exp $
2.\"
984263bc
MD
3.\" Copyright (c) 1980, 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" the American National Standards Committee X3, on Information
8.\" Processing Systems.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\" notice, this list of conditions and the following disclaimer in the
17.\" documentation and/or other materials provided with the distribution.
18.\" 3. All advertising materials mentioning features or use of this software
19.\" must display the following acknowledgement:
20.\" This product includes software developed by the University of
21.\" California, Berkeley and its contributors.
22.\" 4. Neither the name of the University nor the names of its contributors
23.\" may be used to endorse or promote products derived from this software
24.\" without specific prior written permission.
25.\"
26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36.\" SUCH DAMAGE.
37.\"
38.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
899b08f0 39.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
984263bc 40.\"
899b08f0 41.Dd May 21, 2010
984263bc
MD
42.Dt MALLOC 3
43.Os
44.Sh NAME
d0de9052
SW
45.Nm malloc ,
46.Nm calloc ,
47.Nm realloc ,
899b08f0 48.Nm reallocf ,
647552a8 49.Nm free
984263bc
MD
50.Nd general purpose memory allocation functions
51.Sh LIBRARY
52.Lb libc
53.Sh SYNOPSIS
54.In stdlib.h
55.Ft void *
56.Fn malloc "size_t size"
57.Ft void *
58.Fn calloc "size_t number" "size_t size"
59.Ft void *
60.Fn realloc "void *ptr" "size_t size"
61.Ft void *
62.Fn reallocf "void *ptr" "size_t size"
63.Ft void
64.Fn free "void *ptr"
984263bc
MD
65.Sh DESCRIPTION
66The
67.Fn malloc
68function allocates
69.Fa size
899b08f0 70bytes of uninitialized memory.
984263bc
MD
71The allocated space is suitably aligned (after possible pointer coercion)
72for storage of any type of object.
73If the space is at least
74.Em pagesize
75bytes in length (see
76.Xr getpagesize 3 ) ,
77the returned memory will be page boundary aligned as well.
984263bc
MD
78.Pp
79The
80.Fn calloc
81function allocates space for
82.Fa number
83objects,
84each
85.Fa size
86bytes in length.
87The result is identical to calling
88.Fn malloc
89with an argument of
899b08f0 90.Dq "number * size" ,
984263bc
MD
91with the exception that the allocated memory is explicitly initialized
92to zero bytes.
93.Pp
94The
95.Fn realloc
96function changes the size of the previously allocated memory referenced by
97.Fa ptr
98to
99.Fa size
100bytes.
101The contents of the memory are unchanged up to the lesser of the new and
102old sizes.
103If the new size is larger,
104the value of the newly allocated portion of the memory is undefined.
899b08f0 105Upon success, the memory referenced by
984263bc 106.Fa ptr
899b08f0
SW
107is freed and a pointer to the newly allocated memory is returned.
108Note that
109.Fn realloc
110may move the memory allocation, resulting in a different return value than
111.Fa ptr .
984263bc
MD
112If
113.Fa ptr
114is
115.Dv NULL ,
116the
117.Fn realloc
118function behaves identically to
119.Fn malloc
120for the specified size.
121.Pp
122The
123.Fn reallocf
124function call is identical to the realloc function call, except that it
125will free the passed pointer when the requested memory cannot be allocated.
126This is a
52ac7bd7
HP
127.Fx
128/
9bb2a92d 129.Dx
984263bc
MD
130specific API designed to ease the problems with traditional coding styles
131for realloc causing memory leaks in libraries.
132.Pp
133The
134.Fn free
135function causes the allocated memory referenced by
136.Fa ptr
137to be made available for future allocations.
138If
139.Fa ptr
140is
141.Dv NULL ,
142no action occurs.
a623c82d
SW
143.Sh IMPLEMENTATION NOTES
144.Dx Ap s
145.Nm
146implementation is based on a port of the
147.Dx
148kernel slab allocator, appropriately modified for a user process
149environment.
984263bc 150.Pp
a623c82d
SW
151The slab allocator breaks memory allocations up to 8KB into 80 zones.
152Each zone represents a fixed allocation size in multiples of some
153core chunking.
154The chunking is a power-of-2 but the fixed allocation size is not.
155For example, a 1025-byte request is allocated out of the zone with a
156chunking of 128, thus in multiples of 1152 bytes.
157The minimum chunking, used for allocations in the 0-127 byte range,
158is 8 bytes (16 of the 80 zones).
159Beyond that the power-of-2 chunking is between 1/8 and 1/16 of the
160minimum allocation size for any given zone.
984263bc 161.Pp
a623c82d
SW
162As a special case any power-of-2-sized allocation within the zone
163limit (8K) will be aligned to the same power-of-2 rather than that
164zone's (smaller) chunking.
165This is not something you can depend upon for
984263bc 166.Fn malloc ,
a623c82d
SW
167but it is used internally to optimize
168.Xr posix_memalign 3 .
984263bc 169.Pp
a623c82d
SW
170Each zone reserves memory in 64KB blocks.
171Actual memory use tends to be significantly less as only the pages
172actually needed are faulted in.
173Allocations larger than 8K are managed using
174.Xr mmap 2
175and tracked with a hash table.
176.Pp
177The zone mechanism results in well-fitted allocations with little
178waste in a long-running environment which makes a lot of allocations.
179Short-running environments which do not make many allocations will see
180a bit of extra bloat due to the large number of zones but it will
181be almost unnoticeable in the grand scheme of things.
182To reduce bloat further the normal randomized start offset implemented
183in the kernel version of the allocator to improve L1 cache fill is
184disabled in the libc version.
185.Pp
186The zone mechanism also has the nice side effect of greatly reducing
187fragmentation over the original
188.Nm .
189.Pp
a623c82d
SW
190.Fn calloc
191is directly supported by keeping track of newly-allocated zones which
192will be demand-zero'd by the system.
193If the allocation is known to be zero'd we do not bother
194.Fn bzero Ns ing
195it.
196If it is a reused allocation we
197.Fn bzero .
198.Pp
199.Tn POSIX
200threading is supported by duplicating the primary structure.
201A thread entering
202.Fn malloc
203which is unable to immediately acquire a mutex on the last primary
204structure it used will switch to a different primary structure.
205At the moment this is more of a quick hack than a solution, but it works.
984263bc
MD
206.Sh RETURN VALUES
207The
208.Fn malloc
209and
210.Fn calloc
211functions return a pointer to the allocated memory if successful; otherwise
212a
213.Dv NULL
214pointer is returned and
215.Va errno
216is set to
217.Er ENOMEM .
218.Pp
219The
220.Fn realloc
221and
222.Fn reallocf
223functions return a pointer, possibly identical to
224.Fa ptr ,
225to the allocated memory
226if successful; otherwise a
227.Dv NULL
228pointer is returned, and
229.Va errno
230is set to
231.Er ENOMEM
232if the error was the result of an allocation failure.
233The
234.Fn realloc
235function always leaves the original buffer intact
236when an error occurs, whereas
237.Fn reallocf
238deallocates it in this case.
239.Pp
240The
241.Fn free
242function returns no value.
899b08f0
SW
243.Sh EXAMPLES
244When using
245.Fn malloc ,
246be careful to avoid the following idiom:
247.Bd -literal -offset indent
248if ((p = malloc(number * size)) == NULL)
249 err(EXIT_FAILURE, "malloc");
250.Ed
251.Pp
252The multiplication may lead to an integer overflow.
253To avoid this,
254.Fn calloc
255is recommended.
256.Pp
257If
258.Fn malloc
259must be used, be sure to test for overflow:
260.Bd -literal -offset indent
261if (size && number > SIZE_MAX / size) {
262 errno = EOVERFLOW;
263 err(EXIT_FAILURE, "allocation");
264}
265.Ed
266.Pp
267When using
268.Fn realloc ,
269one must be careful to avoid the following idiom:
899b08f0
SW
270.Bd -literal -offset indent
271nsize += 50;
272
273if ((p = realloc(p, nsize)) == NULL)
274 return NULL;
275.Ed
276.Pp
277Do not adjust the variable describing how much memory has been allocated
278until it is known that the allocation has been successful.
279This can cause aberrant program behavior if the incorrect size value is used.
280In most cases, the above example will also leak memory.
281As stated earlier, a return value of
282.Dv NULL
283indicates that the old object still remains allocated.
284Better code looks like this:
285.Bd -literal -offset indent
286newsize = size + 50;
287
288if ((p2 = realloc(p, newsize)) == NULL) {
289
290 if (p != NULL)
291 free(p);
292
293 p = NULL;
294 return NULL;
295}
296
297p = p2;
298size = newsize;
299.Ed
300.Sh DIAGNOSTICS
984263bc
MD
301If
302.Fn malloc ,
303.Fn calloc ,
304.Fn realloc
305or
306.Fn free
a623c82d
SW
307detect an error, a message will be printed to file descriptor
308.Dv STDERR_FILENO
309and the process will dump core.
984263bc 310.Sh SEE ALSO
899b08f0 311.Xr madvise 2 ,
984263bc 312.Xr mmap 2 ,
899b08f0 313.Xr sbrk 2 ,
984263bc 314.Xr alloca 3 ,
899b08f0 315.Xr atexit 3 ,
8469d782 316.Xr emalloc 3 ,
984263bc 317.Xr getpagesize 3 ,
4a365d8b 318.Xr memory 3 ,
e398539c 319.Xr posix_memalign 3
984263bc
MD
320.Sh STANDARDS
321The
322.Fn malloc ,
323.Fn calloc ,
324.Fn realloc
325and
326.Fn free
327functions conform to
328.St -isoC .
329.Sh HISTORY
984263bc
MD
330The
331.Fn reallocf
332function first appeared in
333.Fx 3.0 .
984263bc 334.Pp
a623c82d 335.Dx Ap s
a623c82d 336.Nm
5ba2aca2 337implementation is based on the kernel's slab allocator (see
428daf5b 338.Xr posix_memalign 3 Ap s
a623c82d
SW
339.Sx IMPLEMENTATION NOTES ) .
340It first appeared in
341.Dx 2.3 .
342.Sh AUTHORS
343.An Matt Dillon