diff options
Diffstat (limited to 'man3/malloc.3')
| -rw-r--r-- | man3/malloc.3 | 459 |
1 files changed, 0 insertions, 459 deletions
diff --git a/man3/malloc.3 b/man3/malloc.3 deleted file mode 100644 index b26a1955e..000000000 --- a/man3/malloc.3 +++ /dev/null @@ -1,459 +0,0 @@ -'\" 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> -.PP -.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 -.PP -.RS -4 -Feature Test Macro Requirements for glibc (see -.BR feature_test_macros (7)): -.RE -.PP -.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 (). -.PP -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: -.PP -.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. -.PP -If -.I ptr -is NULL, then the call is equivalent to -.IR malloc(size) , -for all values of -.IR size . -.PP -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). -.PP -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 -.PP -.in +4n -.EX -realloc(ptr, nmemb * size); -.EE -.in -.PP -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. -.PP -The -.BR free () -function returns no value, and preserves -.IR errno . -.PP -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). -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.ad l -.nh -.TS -allbox; -lbx lb lb -l l l. -Interface Attribute Value -T{ -.BR malloc (), -.BR free (), -.BR calloc (), -.BR realloc () -T} Thread safety MT-Safe -.TE -.hy -.ad -.sp 1 -.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. -.PP -.BR malloc () -and related functions rejected sizes greater than -.B PTRDIFF_MAX -starting in glibc 2.30. -.PP -.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 . -.PP -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). -.PP -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. -.PP -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. -.PP -Crashes in memory allocators -are almost always related to heap corruption, such as overflowing -an allocated chunk or freeing the same pointer twice. -.PP -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). -.PP -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. -.PP -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) -.PP -For details of the GNU C library implementation, see -.UR https://sourceware.org/glibc/wiki/MallocInternals -.UE . |