NetBSD/lib/libc/stdlib/malloc.3

.\" $NetBSD: malloc.3,v 1.48 2016/06/01 08:32:05 wiz Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)malloc.3	8.1 (Berkeley) 6/4/93
.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
.\"
.Dd June 1, 2016
.Dt MALLOC 3
.Os
.Sh NAME
.Nm malloc , calloc , realloc , free
.Nd general purpose memory allocation functions
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In stdlib.h
.Ft void *
.Fn malloc "size_t size"
.Ft void *
.Fn calloc "size_t number" "size_t size"
.Ft void *
.Fn realloc "void *ptr" "size_t size"
.Ft void
.Fn free "void *ptr"
.Sh DESCRIPTION
The
.Fn malloc
function allocates
.Fa size
bytes of uninitialized memory.
The allocated space is suitably aligned (after possible pointer coercion)
for storage of any type of object.
.Pp
The
.Fn calloc
function allocates space for
.Fa number
objects,
each
.Fa size
bytes in length.
The result is identical to calling
.Fn malloc
with an argument of
.Dq "number * size" ,
with the exception that the allocated memory is explicitly initialized
to zero bytes.
.Pp
The
.Fn realloc
function changes the size of the previously allocated memory referenced by
.Fa ptr
to
.Fa size
bytes.
The contents of the memory are unchanged up to the lesser of the new and
old sizes.
If the new size is larger,
the value of the newly allocated portion of the memory is undefined.
Upon success, the memory referenced by
.Fa ptr
is freed and a pointer to the newly allocated memory is returned.
.Pp
Note that
.Fn realloc
may move the memory allocation, resulting in a different return value than
.Fa ptr .
If
.Fa ptr
is
.Dv NULL ,
the
.Fn realloc
function behaves identically to
.Fn malloc
for the specified size.
.Pp
The
.Fn free
function causes the allocated memory referenced by
.Fa ptr
to be made available for future allocations.
If
.Fa ptr
is
.Dv NULL ,
no action occurs.
.Sh RETURN VALUES
The
.Fn malloc
and
.Fn calloc
functions return a pointer to the allocated memory if successful; otherwise
a
.Dv NULL
pointer is returned and
.Va errno
is set to
.Er ENOMEM .
.Pp
The
.Fn realloc
function returns a pointer, possibly identical to
.Fa ptr ,
to the allocated memory
if successful; otherwise a
.Dv NULL
pointer is returned, and
.Va errno
is set to
.Er ENOMEM
if the error was the result of an allocation failure.
The
.Fn realloc
function always leaves the original buffer intact
when an error occurs.
If
.Ar size
is 0, either
.Dv NULL
or a pointer that can be safely passed to
.Xr free 3
is returned.
.Pp
The
.Fn free
function returns no value.
.Sh EXAMPLES
When using
.Fn malloc ,
be careful to avoid the following idiom:
.Bd -literal -offset indent
if ((p = malloc(number * size)) == NULL)
	err(EXIT_FAILURE, "malloc");
.Ed
.Pp
The multiplication may lead to an integer overflow.
To avoid this,
.Xr reallocarr 3
is recommended.
.Pp
If
.Fn malloc
must be used, be sure to test for overflow:
.Bd -literal -offset indent
if (size && number > SIZE_MAX / size) {
	errno = EOVERFLOW;
	err(EXIT_FAILURE, "allocation");
}
.Ed
.Pp
The above test is not sufficient in all cases.
For example, multiplying ints requires a different set of checks:
.Bd -literal -offset indent
int num, size;
\&.\&.\&.

/* Avoid invalid requests */
if (size < 0 || num < 0)
	errc(1, EOVERFLOW, "overflow");

/* Check for signed int overflow */
if (size && num > INT_MAX / size)
	errc(1, EOVERFLOW, "overflow");

if ((p = malloc(size * num)) == NULL)
	err(1, "malloc");
.Ed
.Pp
Assuming the implementation checks for integer overflow as
.Nx
does, it is much easier to use
.Fn calloc
or
.Xr reallocarr 3 .
.Pp
The above examples could be simplified to:
.Bd -literal -offset indent
ptr = NULL;
if ((e = reallocarr(&ptr, num, size)))
	errx(1, "reallocarr", strerror(e));
.Ed
.Bd -literal -offset indent
or at the cost of initialization:
if ((p = calloc(num, size)) == NULL)
	err(1, "calloc");
.Ed
.Pp
When using
.Fn realloc ,
one must be careful to avoid the following idiom:
.Bd -literal -offset indent
nsize += 50;

if ((p = realloc(p, nsize)) == NULL)
	return NULL;
.Ed
.Pp
Do not adjust the variable describing how much memory has been allocated
until it is known that the allocation has been successful.
This can cause aberrant program behavior if the incorrect size value is used.
In most cases, the above example will also leak memory.
As stated earlier, a return value of
.Dv NULL
indicates that the old object still remains allocated.
Better code looks like this:
.Bd -literal -offset indent
newsize = size + 50;

if ((p2 = realloc(p, newsize)) == NULL) {

	if (p != NULL)
		free(p);

	p = NULL;
	return NULL;
}

p = p2;
size = newsize;
.Ed
.Sh SEE ALSO
.\" .Xr limits 1 ,
.Xr madvise 2 ,
.Xr mmap 2 ,
.Xr sbrk 2 ,
.Xr aligned_alloc 3 ,
.Xr alloca 3 ,
.Xr atexit 3 ,
.Xr getpagesize 3 ,
.Xr memory 3 ,
.Xr posix_memalign 3 ,
.Xr reallocarr 3
.Pp
For the implementation details, see
.Xr jemalloc 3 .
.Sh STANDARDS
The
.Fn malloc ,
.Fn calloc ,
.Fn realloc
and
.Fn free
functions conform to
.St -isoC .
.Sh HISTORY
A
.Fn free
internal kernel function and a predecessor to
.Fn malloc ,
.Fn alloc ,
first appeared in
.At v1 .
The C Library functions
.Fn alloc
and
.Fn free
appeared in
.At v6 .
The functions
.Fn malloc ,
.Fn calloc ,
and
.Fn realloc
first appeared in
.At v7 .
.Pp
A new implementation by Chris Kingsley was introduced in
.Bx 4.2 ,
followed by a complete rewrite by Poul-Henning Kamp
.Dq ( phk's malloc
or
.Dq new malloc )
which appeared in
.Fx 2.2
and was included in
.Nx 1.5
and
.Ox 2.0 .
These implementations were all
.Xr sbrk 2
based.
.Pp
The
.Xr jemalloc 3
allocator became the default system allocator first in
.Fx 7.0
and then in
.Nx 5.0 .