xref: /netbsd-src/lib/libc/stdlib/malloc.3 (revision a582ce597922319ccdf340494a2470d30d2cadf4)
1.\" $NetBSD: malloc.3,v 1.39 2015/02/05 16:04:35 christos Exp $
2.\"
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. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"     @(#)malloc.3	8.1 (Berkeley) 6/4/93
35.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
36.\"
37.Dd February 5, 2015
38.Dt MALLOC 3
39.Os
40.Sh NAME
41.Nm malloc , calloc , realloc , reallocarray, free
42.Nd general purpose memory allocation functions
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In stdlib.h
47.Ft void *
48.Fn malloc "size_t size"
49.Ft void *
50.Fn calloc "size_t number" "size_t size"
51.Ft void *
52.Fn realloc "void *ptr" "size_t size"
53.Ft void *
54.Fn reallocarray "void *ptr" "size_t number" "size_t size"
55.Ft void
56.Fn free "void *ptr"
57.Sh DESCRIPTION
58The
59.Fn malloc
60function allocates
61.Fa size
62bytes of uninitialized memory.
63The allocated space is suitably aligned (after possible pointer coercion)
64for storage of any type of object.
65.Pp
66The
67.Fn calloc
68function allocates space for
69.Fa number
70objects,
71each
72.Fa size
73bytes in length.
74The result is identical to calling
75.Fn malloc
76with an argument of
77.Dq "number * size" ,
78with the exception that the allocated memory is explicitly initialized
79to zero bytes, and overflow is being checked.
80.Pp
81The
82.Fn realloc
83function changes the size of the previously allocated memory referenced by
84.Fa ptr
85to
86.Fa size
87bytes.
88The contents of the memory are unchanged up to the lesser of the new and
89old sizes.
90If the new size is larger,
91the value of the newly allocated portion of the memory is undefined.
92Upon success, the memory referenced by
93.Fa ptr
94is freed and a pointer to the newly allocated memory is returned.
95.Pp
96The
97.Fn reallocarray
98function is similar to
99.Fn realloc
100except it operates on
101.Fa number
102members of size
103.Fa size
104and checks for integer overflow in the calculation of\
105.Dq "number * size" .
106.Pp
107Note that
108.Fn realloc
109and
110.Fn reallocarray
111may move the memory allocation, resulting in a different return value than
112.Fa ptr .
113If
114.Fa ptr
115is
116.Dv NULL ,
117the
118.Fn realloc
119function behaves identically to
120.Fn malloc
121for the specified size.
122.Pp
123The
124.Fn free
125function causes the allocated memory referenced by
126.Fa ptr
127to be made available for future allocations.
128If
129.Fa ptr
130is
131.Dv NULL ,
132no action occurs.
133.Sh RETURN VALUES
134The
135.Fn malloc
136and
137.Fn calloc
138functions return a pointer to the allocated memory if successful; otherwise
139a
140.Dv NULL
141pointer is returned and
142.Va errno
143is set to
144.Er ENOMEM .
145.Pp
146The
147.Fn realloc
148and
149.Fn reallocarray
150functions return a pointer, possibly identical to
151.Fa ptr ,
152to the allocated memory
153if successful; otherwise a
154.Dv NULL
155pointer is returned, and
156.Va errno
157is set to
158.Er ENOMEM
159if the error was the result of an allocation failure.
160The
161.Fn realloc
162and
163.Fn reallocarray
164functions always leave the original buffer intact
165when an error occurs.
166.Pp
167The
168.Fn free
169function returns no value.
170.Sh EXAMPLES
171When using
172.Fn malloc ,
173be careful to avoid the following idiom:
174.Bd -literal -offset indent
175if ((p = malloc(number * size)) == NULL)
176	err(EXIT_FAILURE, "malloc");
177.Ed
178.Pp
179The multiplication may lead to an integer overflow.
180To avoid this,
181.Fn reallocarray
182is recommended.
183.Pp
184If
185.Fn malloc
186must be used, be sure to test for overflow:
187.Bd -literal -offset indent
188if (size && number > SIZE_MAX / size) {
189	errno = EOVERFLOW;
190	err(EXIT_FAILURE, "allocation");
191}
192.Ed
193.Pp
194The above test is not sufficient in all cases.
195For example, multiplying ints requires a different set of checks:
196.Bd -literal -offset indent
197int num, size;
198\&.\&.\&.
199
200/* Avoid invalid requests */
201if (size < 0 || num < 0)
202	errc(1, EOVERFLOW, "overflow");
203
204/* Check for signed int overflow */
205if (size && num > INT_MAX / size)
206	errc(1, EOVERFLOW, "overflow");
207
208if ((p = malloc(size * num)) == NULL)
209	err(1, "malloc");
210.Ed
211.Pp
212Assuming the implementation checks for integer overflow as
213.Nx
214does, it is much easier to use
215.Fn calloc
216or
217.Fn reallocarray .
218.Pp
219The above examples could be simplified to:
220.Bd -literal -offset indent
221if ((p = reallocarray(NULL, num, size)) == NULL)
222	err(1, "reallocarray");
223.Ed
224.Bd -literal -offset indent
225or at the cost of initialization:
226if ((p = calloc(num, size)) == NULL)
227	err(1, "calloc");
228.Ed
229.Pp
230When using
231.Fn realloc ,
232one must be careful to avoid the following idiom:
233.Pp
234.Bd -literal -offset indent
235nsize += 50;
236
237if ((p = realloc(p, nsize)) == NULL)
238	return NULL;
239.Ed
240.Pp
241Do not adjust the variable describing how much memory has been allocated
242until it is known that the allocation has been successful.
243This can cause aberrant program behavior if the incorrect size value is used.
244In most cases, the above example will also leak memory.
245As stated earlier, a return value of
246.Dv NULL
247indicates that the old object still remains allocated.
248Better code looks like this:
249.Bd -literal -offset indent
250newsize = size + 50;
251
252if ((p2 = realloc(p, newsize)) == NULL) {
253
254	if (p != NULL)
255		free(p);
256
257	p = NULL;
258	return NULL;
259}
260
261p = p2;
262size = newsize;
263.Ed
264.Sh SEE ALSO
265.\" .Xr limits 1 ,
266.Xr madvise 2 ,
267.Xr mmap 2 ,
268.Xr sbrk 2 ,
269.Xr alloca 3 ,
270.Xr atexit 3 ,
271.Xr getpagesize 3 ,
272.Xr memory 3 ,
273.Xr posix_memalign 3
274.Pp
275For the implementation details, see
276.Xr jemalloc 3 .
277.Sh STANDARDS
278The
279.Fn malloc ,
280.Fn calloc ,
281.Fn realloc
282and
283.Fn free
284functions conform to
285.St -isoC .
286.Pp
287The
288.Fn reallocarray
289function first appeared on
290.Ox 5.6
291and
292.Nx 8 .
293