diff options
Diffstat (limited to 'man/man3/malloc.3')
| -rw-r--r-- | man/man3/malloc.3 | 460 |
1 files changed, 460 insertions, 0 deletions
diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 new file mode 100644 index 000000000..e164d588f --- /dev/null +++ b/man/man3/malloc.3 @@ -0,0 +1,460 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2007, 2012, 2018, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:00:59 1993 by Rik Faith (faith@cs.unc.edu) +.\" Clarification concerning realloc, iwj10@cus.cam.ac.uk (Ian Jackson), 950701 +.\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de) +.\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap(). +.\" +.\" FIXME . Review http://austingroupbugs.net/view.php?id=374 +.\" to see what changes are required on this page. +.\" +.TH malloc 3 (date) "Linux man-pages (unreleased)" +.SH NAME +malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.P +.BI "void *malloc(size_t " size ); +.BI "void free(void *_Nullable " ptr ); +.BI "void *calloc(size_t " nmemb ", size_t " size ); +.BI "void *realloc(void *_Nullable " ptr ", size_t " size ); +.BI "void *reallocarray(void *_Nullable " ptr ", size_t " nmemb ", size_t " size ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR reallocarray (): +.nf + Since glibc 2.29: + _DEFAULT_SOURCE + glibc 2.28 and earlier: + _GNU_SOURCE +.fi +.SH DESCRIPTION +.SS malloc() +The +.BR malloc () +function allocates +.I size +bytes and returns a pointer to the allocated memory. +.IR "The memory is not initialized" . +If +.I size +is 0, then +.BR malloc () +returns a unique pointer value that can later be successfully passed to +.BR free (). +(See "Nonportable behavior" for portability issues.) +.SS free() +The +.BR free () +function frees the memory space pointed to by +.IR ptr , +which must have been returned by a previous call to +.BR malloc () +or related functions. +Otherwise, or if +.I ptr +has already been freed, undefined behavior occurs. +If +.I ptr +is NULL, no operation is performed. +.SS calloc() +The +.BR calloc () +function allocates memory for an array of +.I nmemb +elements of +.I size +bytes each and returns a pointer to the allocated memory. +The memory is set to zero. +If +.I nmemb +or +.I size +is 0, then +.BR calloc () +returns a unique pointer value that can later be successfully passed to +.BR free (). +.P +If the multiplication of +.I nmemb +and +.I size +would result in integer overflow, then +.BR calloc () +returns an error. +By contrast, +an integer overflow would not be detected in the following call to +.BR malloc (), +with the result that an incorrectly sized block of memory would be allocated: +.P +.in +4n +.EX +malloc(nmemb * size); +.EE +.in +.SS realloc() +The +.BR realloc () +function changes the size of the memory block pointed to by +.I ptr +to +.I size +bytes. +The contents of the memory +will be unchanged in the range from the start of the region +up to the minimum of the old and new sizes. +If the new size is larger than the old size, the added memory will +.I not +be initialized. +.P +If +.I ptr +is NULL, then the call is equivalent to +.IR malloc(size) , +for all values of +.IR size . +.P +If +.I size +is equal to zero, +and +.I ptr +is not NULL, then the call is equivalent to +.I free(ptr) +(but see "Nonportable behavior" for portability issues). +.P +Unless +.I ptr +is NULL, it must have been returned by an earlier call to +.B malloc +or related functions. +If the area pointed to was moved, a +.I free(ptr) +is done. +.SS reallocarray() +The +.BR reallocarray () +function changes the size of (and possibly moves) +the memory block pointed to by +.I ptr +to be large enough for an array of +.I nmemb +elements, each of which is +.I size +bytes. +It is equivalent to the call +.P +.in +4n +.EX +realloc(ptr, nmemb * size); +.EE +.in +.P +However, unlike that +.BR realloc () +call, +.BR reallocarray () +fails safely in the case where the multiplication would overflow. +If such an overflow occurs, +.BR reallocarray () +returns an error. +.SH RETURN VALUE +The +.BR malloc (), +.BR calloc (), +.BR realloc (), +and +.BR reallocarray () +functions return a pointer to the allocated memory, +which is suitably aligned for any type that fits into +the requested size or less. +On error, these functions return NULL and set +.IR errno . +Attempting to allocate more than +.B PTRDIFF_MAX +bytes is considered an error, as an object that large +could cause later pointer subtraction to overflow. +.P +The +.BR free () +function returns no value, and preserves +.IR errno . +.P +The +.BR realloc () +and +.BR reallocarray () +functions return NULL if +.I ptr +is not NULL and the requested size is zero; +this is not considered an error. +(See "Nonportable behavior" for portability issues.) +Otherwise, the returned pointer may be the same as +.I ptr +if the allocation was not moved +(e.g., there was room to expand the allocation in-place), or different from +.I ptr +if the allocation was moved to a new address. +If these functions fail, +the original block is left untouched; it is not freed or moved. +.SH ERRORS +.BR calloc (), +.BR malloc (), +.BR realloc (), +and +.BR reallocarray () +can fail with the following error: +.TP +.B ENOMEM +Out of memory. +Possibly, the application hit the +.B RLIMIT_AS +or +.B RLIMIT_DATA +limit described in +.BR getrlimit (2). +Another reason could be that +the number of mappings created by the caller process +exceeded the limit specified by +.IR /proc/sys/vm/max_map_count . +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR malloc (), +.BR free (), +.BR calloc (), +.BR realloc () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR malloc () +.TQ +.BR free () +.TQ +.BR calloc () +.TQ +.BR realloc () +C11, POSIX.1-2008. +.TP +.BR reallocarray () +None. +.SH HISTORY +.TP +.BR malloc () +.TQ +.BR free () +.TQ +.BR calloc () +.TQ +.BR realloc () +POSIX.1-2001, C89. +.TP +.BR reallocarray () +glibc 2.26. +OpenBSD 5.6, FreeBSD 11.0. +.P +.BR malloc () +and related functions rejected sizes greater than +.B PTRDIFF_MAX +starting in glibc 2.30. +.P +.BR free () +preserved +.I errno +starting in glibc 2.33. +.SH NOTES +By default, Linux follows an optimistic memory allocation strategy. +This means that when +.BR malloc () +returns non-NULL there is no guarantee that the memory really +is available. +In case it turns out that the system is out of memory, +one or more processes will be killed by the OOM killer. +For more information, see the description of +.I /proc/sys/vm/overcommit_memory +and +.I /proc/sys/vm/oom_adj +in +.BR proc (5), +and the Linux kernel source file +.IR Documentation/vm/overcommit\-accounting.rst . +.P +Normally, +.BR malloc () +allocates memory from the heap, and adjusts the size of the heap +as required, using +.BR sbrk (2). +When allocating blocks of memory larger than +.B MMAP_THRESHOLD +bytes, the glibc +.BR malloc () +implementation allocates the memory as a private anonymous mapping using +.BR mmap (2). +.B MMAP_THRESHOLD +is 128\ kB by default, but is adjustable using +.BR mallopt (3). +Prior to Linux 4.7 +allocations performed using +.BR mmap (2) +were unaffected by the +.B RLIMIT_DATA +resource limit; +since Linux 4.7, this limit is also enforced for allocations performed using +.BR mmap (2). +.P +To avoid corruption in multithreaded applications, +mutexes are used internally to protect the memory-management +data structures employed by these functions. +In a multithreaded application in which threads simultaneously +allocate and free memory, +there could be contention for these mutexes. +To scalably handle memory allocation in multithreaded applications, +glibc creates additional +.I memory allocation arenas +if mutex contention is detected. +Each arena is a large region of memory that is internally allocated +by the system +(using +.BR brk (2) +or +.BR mmap (2)), +and managed with its own mutexes. +.P +If your program uses a private memory allocator, +it should do so by replacing +.BR malloc (), +.BR free (), +.BR calloc (), +and +.BR realloc (). +The replacement functions must implement the documented glibc behaviors, +including +.I errno +handling, size-zero allocations, and overflow checking; +otherwise, other library routines may crash or operate incorrectly. +For example, if the replacement +.IR free () +does not preserve +.IR errno , +then seemingly unrelated library routines may +fail without having a valid reason in +.IR errno . +Private memory allocators may also need to replace other glibc functions; +see "Replacing malloc" in the glibc manual for details. +.P +Crashes in memory allocators +are almost always related to heap corruption, such as overflowing +an allocated chunk or freeing the same pointer twice. +.P +The +.BR malloc () +implementation is tunable via environment variables; see +.BR mallopt (3) +for details. +.SS Nonportable behavior +The behavior of +these functions when the requested size is zero +is glibc specific; +other implementations may return NULL without setting +.IR errno , +and portable POSIX programs should tolerate such behavior. +See +.BR realloc (3p). +.P +POSIX requires memory allocators +to set +.I errno +upon failure. +However, the C standard does not require this, and applications +portable to non-POSIX platforms should not assume this. +.P +Portable programs should not use private memory allocators, +as POSIX and the C standard do not allow replacement of +.BR malloc (), +.BR free (), +.BR calloc (), +and +.BR realloc (). +.SH EXAMPLES +.EX +#include <err.h> +#include <stddef.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +\& +#define MALLOCARRAY(n, type) ((type *) my_mallocarray(n, sizeof(type))) +#define MALLOC(type) MALLOCARRAY(1, type) +\& +static inline void *my_mallocarray(size_t nmemb, size_t size); +\& +int +main(void) +{ + char *p; +\& + p = MALLOCARRAY(32, char); + if (p == NULL) + err(EXIT_FAILURE, "malloc"); +\& + strlcpy(p, "foo", 32); + puts(p); +} +\& +static inline void * +my_mallocarray(size_t nmemb, size_t size) +{ + return reallocarray(NULL, nmemb, size); +} +.EE +.SH SEE ALSO +.\" http://g.oswego.edu/dl/html/malloc.html +.\" A Memory Allocator - by Doug Lea +.\" +.\" http://www.bozemanpass.com/info/linux/malloc/Linux_Heap_Contention.html +.\" Linux Heap, Contention in free() - David Boreham +.\" +.\" http://www.citi.umich.edu/projects/linux-scalability/reports/malloc.html +.\" malloc() Performance in a Multithreaded Linux Environment - +.\" Check Lever, David Boreham +.\" +.ad l +.nh +.BR valgrind (1), +.BR brk (2), +.BR mmap (2), +.BR alloca (3), +.BR malloc_get_state (3), +.BR malloc_info (3), +.BR malloc_trim (3), +.BR malloc_usable_size (3), +.BR mallopt (3), +.BR mcheck (3), +.BR mtrace (3), +.BR posix_memalign (3) +.P +For details of the GNU C library implementation, see +.UR https://sourceware.org/glibc/wiki/MallocInternals +.UE . |