path: root/usr/src/man/man3c/malloc.3c

.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2017 Nexenta Systems, Inc.
.\" Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
.\"
.Dd September 12, 2019
.Dt MALLOC 3C
.Os
.Sh NAME
.Nm malloc ,
.Nm calloc ,
.Nm free ,
.Nm freezero ,
.Nm memalign ,
.Nm realloc ,
.Nm reallocf ,
.Nm reallocarray ,
.Nm recallocarray ,
.Nm valloc ,
.Nm alloca
.Nd memory allocator
.Sh SYNOPSIS
.In stdlib.h
.Ft void *
.Fo malloc
.Fa "size_t size"
.Fc
.Ft void *
.Fo calloc
.Fa "size_t nelem"
.Fa "size_t elsize"
.Fc
.Ft void
.Fo free
.Fa "void *ptr"
.Fc
.Ft void
.Fo freezero
.Fa "void *ptr"
.Fa "size_t size"
.Fc
.Ft void *
.Fo memalign
.Fa "size_t alignment"
.Fa "size_t size"
.Fc
.Ft void *
.Fo realloc
.Fa "void *ptr"
.Fa "size_t size"
.Fc
.Ft void *
.Fo reallocf
.Fa "void *ptr"
.Fa "size_t size"
.Fc
.Ft void *
.Fo reallocarray
.Fa "void *ptr"
.Fa "size_t nelem"
.Fa "size_t elsize"
.Fc
.Ft void *
.Fo recallocarray
.Fa "void *ptr"
.Fa "size_t oldnelem"
.Fa "size_t newnelem"
.Fa "size_t elsize"
.Fc
.Ft void *
.Fo valloc
.Fa "size_t size"
.Fc
.In alloca.h
.Ft void *
.Fo alloca
.Fa "size_t size"
.Fc
.Sh DESCRIPTION
The
.Fn malloc
and
.Fn free
functions provide a simple, general-purpose memory allocation package.
The
.Fn malloc
function returns a pointer to a block of at least
.Fa size
bytes suitably aligned for any use.
If the space assigned by
.Fn malloc
is overrun, the results are undefined.
.Pp
The argument to
.Fn free
is a pointer to a block previously allocated by
.Fn malloc ,
.Fn calloc ,
.Fn realloc ,
.Fn reallocf ,
.Fn reallocarray ,
or
.Fn recallocarray .
After
.Fn free
is executed, this space is made available for further allocation by the
application, though not returned to the system.
Memory is returned to the system only upon termination of the application.
If
.Fa ptr
is a null pointer, no action occurs.
If a random number is passed to
.Fn free ,
the results are undefined.
.Pp
The
.Fn freezero
function is similar to the
.Fn free
function except it ensures memory is explicitly discarded.
If
.Fa ptr
is
.Dv NULL ,
no action occurs.
If
.Fa ptr
is not
.Dv NULL ,
the
.Fa size
argument must be equal or smaller than the size of the earlier allocation that
returned
.Fa ptr .
.Fn freezero
guarantees the memory range starting at
.Fa ptr
with length
.Fa size
is discarded while deallocating the whole object originally allocated.
.Pp
The
.Fn calloc
function allocates space for an array of
.Fa nelem
elements of size
.Fa elsize .
The space is initialized to zeros.
.Pp
The
.Fn memalign
function allocates
.Fa size
bytes on a specified alignment boundary and returns a pointer to the allocated
block.
The value of the returned address is guaranteed to be an even multiple of
.Fa alignment .
The value of
.Fa alignment
must be a power of two and must be greater than or equal to the size of a word.
.Pp
The
.Fn realloc
function changes the size of the block pointed to by
.Fa ptr
to
.Fa size
bytes and returns a pointer to the
.Pq possibly moved
block.
The contents will be unchanged up to the lesser of the new and old sizes.
If the new size of the block requires movement of the block, the space for the
previous instantiation of the block is freed.
If the new size is larger, the contents of the newly allocated portion of the
block are unspecified.
If
.Fa ptr
is
.Dv NULL ,
.Fn realloc
behaves like
.Fn malloc
for the specified size.
If
.Fa size
is 0 and
.Fa ptr
is not a null pointer, the space pointed to is freed.
.Pp
The
.Fn reallocf
function behaves in the same way as
.Fn realloc
except that the passed pointer is freed automatically on failure.
.Pp
The
.Fn reallocarray
function is similar to
.Fn realloc ,
but operates on
.Fa nelem
elements of size
.Fa elsize
and checks for overflow in
.Fa nelem Ns * Ns Fa elsize
calculation.
.Pp
The
.Fn recallocarray
function is similar to
.Fn reallocarray
except it ensures newly allocated memory is cleared similar to
.Fn calloc .
If
.Fa ptr
is
.Dv NULL ,
.Fa oldnelem
is ignored and the call is equivalent to
.Fn calloc .
If
.Fa ptr
is not
.Dv NULL ,
.Fa oldnelem
must be a value such that
.Fa oldnelem Ns * Ns Fa elsize
is the size of the earlier allocation that returned
.Fa ptr ,
otherwise the behaviour is undefined.
.Pp
The
.Fn valloc
function has the same effect as
.Fn malloc ,
except that the allocated memory will be aligned to a multiple of the value
returned by
.Nm sysconf Ns Pq Dv _SC_PAGESIZE .
.Pp
The
.Fn alloca
function allocates
.Fa size
bytes of space in the stack frame of the caller, and returns a pointer to the
allocated block.
This temporary space is automatically freed when the caller returns.
If the allocated block is beyond the current stack limit, the resulting behavior
is undefined.
.Sh RETURN VALUES
Upon successful completion, each of the allocation functions returns a pointer
to space suitably aligned
.Pq after possible pointer coercion
for storage of any type of object.
.Pp
If there is no available memory,
.Fn malloc ,
.Fn calloc ,
.Fn realloc ,
.Fn reallocf ,
.Fn reallocarray ,
.Fn recallocarray ,
.Fn memalign ,
and
.Fn valloc
return a null pointer.
.Pp
When
.Fn realloc
is called with
.Fa size
> 0 and returns
.Dv NULL ,
the block pointed to by
.Fa ptr
is left intact.
By contrast, when
.Fn reallocf
is called with
.Fa size
> 0 and returns
.Dv NULL ,
the block pointed to by
.Fa ptr
will have been freed.
.Pp
If
.Fa size ,
.Fa nelem ,
or
.Fa elsize
is 0, either a null pointer or a unique pointer that can be passed to
.Fn free
is returned.
.Pp
If
.Fn malloc ,
.Fn calloc ,
.Fn realloc ,
.Fn reallocf ,
.Fn reallocarray ,
or
.Fn recallocarray
returns unsuccessfully,
.Va errno
will be set to indicate the error.
The
.Fn free
and
.Fn freezero
functions do not set
.Va errno .
.Sh ERRORS
The
.Fn malloc ,
.Fn calloc ,
.Fn realloc ,
.Fn reallocf ,
and
.Fn reallocarray
functions will fail if:
.Bl -tag -width Er
.It Er ENOMEM
The physical limits of the system are exceeded by
.Fa size
bytes of memory which cannot be allocated, or there's integer overflow in
.Fn reallocarray .
.It Er EAGAIN
There is not enough memory available to allocate
.Fa size
bytes of memory; but the application could try again later.
.El
.Pp
The
.Fn recallocarray
function will fail if:
.Bl -tag -width Er
.It Er EINVAL
.Fa ptr
is not
.Dv NULL
and multiplying
.Fa oldnelem
and
.Fa elsize
results in integer overflow.
.El
.Sh USAGE
Portable applications should avoid using
.Fn valloc
but should instead use
.Fn malloc
or
.Xr mmap 2 .
On systems with a large page size, the number of successful
.Fn valloc
operations might be 0.
.Pp
These default memory allocation routines are safe for use in multithreaded
applications but are not scalable.
Concurrent accesses by multiple threads are single-threaded through the use of a
single lock.
Multithreaded applications that make heavy use of dynamic memory allocation
should be linked with allocation libraries designed for concurrent access, such
as
.Xr libumem 3LIB
or
.Xr libmtmalloc 3LIB .
Applications that want to avoid using heap allocations
.Pq with Xr brk 2
can do so by using either
.Xr libumem 3LIB
or
.Xr libmapmalloc 3LIB .
The allocation libraries
.Xr libmalloc 3LIB
and
.Xr libbsdmalloc 3LIB
are available for special needs.
.Pp
Comparative features of the various allocation libraries can be found in the
.Xr umem_alloc 3MALLOC
manual page.
.Sh INTERFACE STABILITY
The
.Fn malloc ,
.Fn calloc ,
.Fn free ,
.Fn realloc ,
.Fn valloc
functions are
.Sy Standard.
.Pp
The
.Fn freezero ,
.Fn reallocf ,
.Fn reallocarray ,
and
.Fn recallocarray
functions are
.Sy Committed .
.Pp
The
.Fn memalign
and
.Fn alloca
functions are
.Sy Stable .
.Sh MT-LEVEL
.Sy Safe.
.Sh SEE ALSO
.Xr brk 2 ,
.Xr getrlimit 2 ,
.Xr libbsdmalloc 3LIB ,
.Xr libmalloc 3LIB ,
.Xr libmapmalloc 3LIB ,
.Xr libmtmalloc 3LIB ,
.Xr libumem 3LIB ,
.Xr umem_alloc 3MALLOC ,
.Xr watchmalloc 3MALLOC ,
.Xr attributes 7
.Sh WARNINGS
Undefined results will occur if the size requested for a block of memory
exceeds the maximum size of a process's heap, which can be obtained with
.Xr getrlimit 2 .
.Pp
The
.Fn alloca
function is machine-, compiler-, and most of all, system-dependent.
Its use is strongly discouraged.