svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
free(3c)
Standard C Library Functions malloc(3C)
NAME
malloc, calloc, memalign, realloc, reallocarray, reallocf, valloc,
free, freezero, freezeroall, malloc_usable_size - memory allocator
SYNOPSIS
#include <stdlib.h>
void *malloc(size_t size);
void *calloc(size_t nelem, size_t elsize);
void *memalign(size_t alignment, size_t size);
void *realloc(void *ptr, size_t size);
void *reallocarray(void *ptr, size_t nelem, size_t elsize);
void *reallocf(void *ptr, size_t size);
void *valloc(size_t size);
size_t malloc_usable_size(void *ptr);
void free(void *ptr);
void freezero(void *ptr, size_t size);
void freezeroall(void *ptr);
DESCRIPTION
These functions provide a simple, general-purpose memory allocation
package. If the space assigned by any of the memory allocation func‐
tions is overrun, the results are undefined, except as noted in the ADI
INTERACTION section.
The malloc() function allocates and returns a pointer to a block of at
least size bytes suitably aligned for any use. The initial contents of
the memory in this block are unspecified.
The calloc() function allocates space for an array of nelem elements of
size elsize and returns a pointer to the allocated block. The space is
initialized to zeros.
The memalign() function allocates 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 alignment. The
value of alignment must be a power of two and must be greater than or
equal to the size of a word.
The realloc() function changes the size of the block pointed to by ptr
to size bytes and returns a pointer to the (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 size is 0, the space pointed to by ptr is freed and a
newly allocated block is returned, as if by a call to malloc(0). If ptr
is NULL, realloc() behaves like malloc() for the specified size.
The reallocarray() function behaves like realloc() except that the new
size of the allocation will be large enough for an array of nelem ele‐
ments of size elsize. If padding is necessary to ensure proper align‐
ment of entries in the array, the caller is responsible for including
that in the elsize parameter.
The reallocf() function behaves like realloc() except that if alloca‐
tion fails, the block pointed to by ptr will be freed.
The valloc() function has the same effect as malloc(), except that the
allocated memory will be aligned to a multiple of the value returned by
sysconf(_SC_PAGESIZE).
The argument to free() is a pointer to a block previously allocated by
one of these memory allocation functions. After free() is executed,
this space is made available for further allocation by the application.
Memory might not be returned to the system until termination of the
application. If ptr is a null pointer, no action occurs. If ptr is not
a null pointer, and not a value previously returned by one of these
memory allocation functions, or if the same non-null value is passed
more than once per allocation, the results are undefined.
The malloc_usable_size() function returns the number of bytes of allo‐
cated memory in a block at ptr that was allocated by one of these mem‐
ory allocation functions and which has not yet been freed. The size
returned may be larger than the original size requested, though pro‐
grams should not rely on being able to use more bytes than originally
requested. This will not include the size of any internal bookkeeping
data, red zones, or other memory that the program cannot safely read or
write as part of this block. If ptr is a null pointer, 0 is returned.
If ptr is not a null pointer, and not a value previously returned by
one of these memory allocation functions that has not yet been freed,
the results are undefined - the function may return 0 and set errno to
EINVAL if it successfully detects an invalid pointer, but it is not
guaranteed to detect all possible invalid pointers and may return an
incorrect size or cause a program fault.
The freezero() and freezeroall() functions overwrite the contents of
the memory buffer with zeros before passing it to free(), if ptr is not
NULL. freezero() writes zeros up to the provided size or the size
returned by malloc_usable_size(), whichever is smaller. freezeroall()
writes zeros for the entire size returned by malloc_usable_size().
ADI INTERACTION
On Oracle SPARC systems with support for the Application Data Integrity
(ADI) feature the default set of malloc() functions support the ADIHEAP
security extension. When the ADIHEAP security extension is enabled for
the calling program, malloc() and related functions will use the SPARC
Application Data Integrity APIs to provide detection of buffer over‐
runs, out of bounds pointers, use after free errors, use after reallo‐
cation errors, and stale pointer errors. For more information, see the
adi(7) and sxadm(8) manual pages.
By default, when ADIHEAP is enabled, ADI version mismatches on store
instructions produce a disrupting trap, which means that the associated
SIGSEGV signal may be delivered some number of instructions after the
offending store, and that may make it more difficult to debug some pro‐
grams. To force a precise trap for ADI version mismatches on store
instructions, set the environment variable _LIBC_ADI_PRECISE. The value
to which it is set is irrelevant; what matters is the existence of the
environment variable. Setting _LIBC_ADI_PRECISE might have a perfor‐
mance impact; the magnitude of the impact depends on the percentage and
pattern of the store instructions in the program. Because of that, it
is recommended that _LIBC_ADI_PRECISE be set only for debugging pur‐
poses.
ADI version mismatches on load instructions always produce a precise
trap, with no additional impact on performance.
RETURN VALUES
Upon successful completion, each of the allocation functions returns a
pointer to space suitably aligned (after possible pointer coercion) for
storage of any type of object.
If size, nelem, or elsize is 0, the allocation functions, except for
memalign() and valloc(), return a unique non-null pointer that can be
passed to free(). These pointers should not be dereferenced. The mema‐
lign() and valloc() functions return null pointers when the size param‐
eter is 0.
If there is not enough memory available, the allocation functions
return a null pointer and set errno.
When realloc() or reallocarray() return NULL, the block pointed to by
ptr is left intact. If size, nelem, or elsize is 0, the block pointed
to by ptr is freed, and a unique pointer that can be passed to free()
is returned.
If one of the allocation functions returns unsuccessfully, errno will
be set to indicate the error. The free() function does not set errno.
The malloc_usable_size() function returns a size (which may be 0) on
success, and 0 on failure. In the event of failure, errno will also be
set.
ERRORS
The memory allocation functions will fail if:
ENOMEM The limits of the system are exceeded by the requested amount
of memory, which cannot be allocated.
EAGAIN There is not enough memory available at this point in time to
allocate the requested amount of memory; but the application
could try again later.
The calloc() and reallocarray() functions will also fail if:
ENOMEM The multiplication of the nelem and elsize parameters would
lead to an integer overflow.
The memalign() function may also fail if:
EINVAL The value of the alignment parameter is not a power of two
multiple of sizeof(void *), or the size parameter is zero, or
the combination of the two would lead to an integer overflow.
The valloc() function may also fail if:
EINVAL The size parameter, when aligned to the pagesize, would lead
to an integer overflow.
The malloc_usable_size() function may fail if:
EINVAL The pointer provided is not a valid pointer returned by one
of the memory allocation functions described on this page.
USAGE
Portable applications should avoid using valloc() but should instead
use posix_memalign(3C) or mmap(2). On systems with a large page size,
the number of successful valloc() operations might be 0.
Memory allocated by these functions may be on pages with the PROT_EXEC
access protections disabled to block execution of machine instructions,
depending on the system settings for NXHEAP in sxadm(8) and any -z
sx=nxheap options that were passed to ld(1) when linking the applica‐
tion. These settings may be overridden for individual pages by calling
mprotect(2).
These default memory allocation routines are safe for use in multi‐
threaded applications but are not scalable. Concurrent accesses by mul‐
tiple threads are single-threaded through the use of a single lock.
Multithreaded applications that make heavy use of dynamic memory allo‐
cation should be linked with allocation libraries designed for concur‐
rent access, such as libumem(3LIB) or libmtmalloc(3LIB). Applications
that want to avoid using heap allocations (with brk(2)) can do so by
using either libumem(3LIB) or libmapmalloc(3LIB). The allocation
libraries libmalloc(3LIB) and libbsdmalloc(3LIB) are available for spe‐
cial needs. Further comparative features of the various allocation
libraries can be found in the ALTERNATIVE IMPLEMENTATIONS section
below.
Mixing multiple memory allocation libraries in a single program is not
expected to work well. Passing a pointer allocated by one library to
the free(), realloc(), or malloc_usable_size() functions from another
library is undefined, and may cause memory corruption or program
faults.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSafe _ Standard‐
See below.
See standards(7) for descriptions of the following standards:
tab() box; cw(2.2i) |cw(3.3i) lw(2.2i) |lw(3.3i) INTERFACESAPPLICABLE
STANDARDS _ T{
malloc()
calloc()
realloc()
free()
T}T{
C89 through C11,
POSIX.1-1990 through 2008,
SUS through SUSv4,
XPG1 through XPG7
T} _
valloc()
T{
SUS through SUSv2,
XPG4v2 through XPG5
T} _ T{
freezero()
freezeroall()
malloc_usable_size()
memalign()
reallocarray()
reallocf()
T} None
SEE ALSO
brk(2), getrlimit(2), mprotect(2), adi(3C), alloca(3C), posix_mema‐
lign(3C), libadimalloc(3LIB), libbsdmalloc(3LIB), libmalloc(3LIB),
libmapmalloc(3LIB), libmtmalloc(3LIB), libumem(3LIB), umem_alloc(3MAL‐
LOC), watchmalloc(3MALLOC), adi(7), attributes(7), standards(7),
sxadm(8)
WARNINGS
Undefined results will occur if the size requested for a block of mem‐
ory exceeds the maximum size of a process's heap, which can be obtained
with getrlimit(2).
ALTERNATIVE IMPLEMENTATIONS
The functions described in this page are all exported from libc.so.1
with the NODIRECT flag to prevent direct bindings and allow easy inter‐
position of alternative implementations, either by linking to another
library or by using the LD_PRELOAD functionality of the runtime linker,
ld.so.1(1). Alternative implementations cannot be dynamically loaded
with dlopen(3C) during runtime because there must be only one manager
of the process heap.
Oracle Solaris includes a number of alternative implementations with
different characteristics that make them suitable for usage in various
scenarios. The following list compares the features of the malloc(3C),
bsdmalloc(3MALLOC), libadimalloc(3LIB), malloc(3MALLOC), mapmal‐
loc(3MALLOC), mtmalloc(3MALLOC), libumem(3LIB), and watchmalloc(3MAL‐
LOC), libraries.
o The default malloc(3C) and malloc(3MALLOC) functions use a
single global lock to ensure that only one thread at a time
can allocate memory. The libumem(3LIB), libadimalloc(3LIB),
and mtmalloc(3MALLOC) functions support concurrent alloca‐
tions. The bsdmalloc(3MALLOC) functions have no support for
concurrency.
o The bsdmalloc(3MALLOC) functions afford better performance
but are space-inefficient and not thread-safe. They also
maintain compatibility with historical semantics from the
BSD environment of SunOS 4 releases.
o The malloc(3MALLOC) functions are space-efficient but have
slower performance.
o The default malloc(3C) functions are a trade-off between
performance and space-efficiency.
o The mtmalloc(3MALLOC) functions provide fast, concurrent
malloc() implementations that are not space-efficient.
o The libumem(3LIB) functions provide a fast, concurrent allo‐
cation implementation that in most cases is more space-effi‐
cient than mtmalloc(3MALLOC).
o The libumem(3LIB), libadimalloc(3LIB), mtmalloc(3MALLOC),
and watchmalloc(3MALLOC) libraries provide additional sup‐
port for debugging memory allocation problems.
o The default malloc(3C) functions, the libumem(3LIB) func‐
tions, and the libadimalloc(3LIB) functions offer the option
to provide detection of buffer overruns, out of bounds
pointers, stale pointers, and use after free errors using
the SPARC Application Data Integrity (ADI) feature. These
are enabled by default in libadimalloc, while the others
only use these features if the ADIHEAP security extension is
enabled as described above. Using these features reduces the
space efficiency of allocations with these libraries, and
may affect application performance.
o Most of these implementations use heap allocations managed
with the brk(2) system call. The libmapmalloc(3LIB) func‐
tions instead use mmap(2) to reserve memory to allocate
blocks from, allowing applications to use brk(2) for their
own purposes. libumem(3LIB) allocates heap memory by
default, but offers an option to use mmap(2) instead, as
described in the umem_alloc(3MALLOC) manual page.
When implementing an alternative implementation of these functions for
general use by other software, a library must provide at least all of
the following:
calloc()
free()
malloc()
malloc_usable_size()
memalign()
realloc()
Replacements for the following may be optionally provided:
freezero()
freezeroall()
reallocarray()
reallocf()
valloc()
If replacements are not provided, the default implementations of
freezero(), freezeroall(), reallocarray(), reallocf(), and valloc()
will call the free(), malloc_usable_size(), realloc(), and memalign()
functions provided by the active allocation library.
Replacements for the functions aligned_alloc(3C) and posix_memalign(3C)
should not be provided by alternative implementations. These functions
are provided by libc(3LIB), and call the memalign() and malloc() func‐
tions provided by the active allocation library. They are therefore
compatible with all alternative malloc implementations that fully sup‐
port those functions.
Additional functions may be required in the future as APIs evolve.
HISTORY
The malloc(), calloc(), memalign(), realloc(), valloc(), and free()
functions have been included in all releases of SunOS and Solaris.
The malloc_usable_size() function was defined in GNU libc 2.0, and was
added to Oracle Solaris in the Oracle Solaris 11.4.10 release.
The reallocarray() function was defined in OpenBSD 5.6, and was added
to Oracle Solaris in the Oracle Solaris 11.4.10 release.
The reallocf() function was defined in FreeBSD 3.0, and was added to
Oracle Solaris in the Oracle Solaris 11.4.12 release.
The freezero() function was defined in OpenBSD 6.2, and was added to
Oracle Solaris in the Oracle Solaris 11.4.42 release.
The freezeroall() function was introduced in the Oracle Solaris 11.4.42
release.
Oracle Solaris 11.4 21 Oct 2021 malloc(3C)