diff options
Diffstat (limited to 'man3/mallopt.3')
| -rw-r--r-- | man3/mallopt.3 | 619 |
1 files changed, 0 insertions, 619 deletions
diff --git a/man3/mallopt.3 b/man3/mallopt.3 deleted file mode 100644 index 822487251..000000000 --- a/man3/mallopt.3 +++ /dev/null @@ -1,619 +0,0 @@ -.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.TH mallopt 3 (date) "Linux man-pages (unreleased)" -.SH NAME -mallopt \- set memory allocation parameters -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <malloc.h> -.P -.BI "int mallopt(int " param ", int " value ); -.fi -.SH DESCRIPTION -The -.BR mallopt () -function adjusts parameters that control the behavior of the -memory-allocation functions (see -.BR malloc (3)). -The -.I param -argument specifies the parameter to be modified, and -.I value -specifies the new value for that parameter. -.P -The following values can be specified for -.IR param : -.TP -.B M_ARENA_MAX -If this parameter has a nonzero value, -it defines a hard limit on the maximum number of arenas that can be created. -An arena represents a pool of memory that can be used by -.BR malloc (3) -(and similar) calls to service allocation requests. -Arenas are thread safe and -therefore may have multiple concurrent memory requests. -The trade-off is between the number of threads and the number of arenas. -The more arenas you have, the lower the per-thread contention, -but the higher the memory usage. -.IP -The default value of this parameter is 0, -meaning that the limit on the number of arenas is determined -according to the setting of -.BR M_ARENA_TEST . -.IP -This parameter has been available since glibc 2.10 via -.BR \-\-enable\-experimental\-malloc , -and since glibc 2.15 by default. -In some versions of the allocator there was no limit on the number -of created arenas (e.g., CentOS 5, RHEL 5). -.IP -When employing newer glibc versions, applications may in -some cases exhibit high contention when accessing arenas. -In these cases, it may be beneficial to increase -.B M_ARENA_MAX -to match the number of threads. -This is similar in behavior to strategies taken by tcmalloc and jemalloc -(e.g., per-thread allocation pools). -.TP -.B M_ARENA_TEST -This parameter specifies a value, in number of arenas created, -at which point the system configuration will be examined -to determine a hard limit on the number of created arenas. -(See -.B M_ARENA_MAX -for the definition of an arena.) -.IP -The computation of the arena hard limit is implementation-defined -and is usually calculated as a multiple of the number of available CPUs. -Once the hard limit is computed, the result is final and constrains -the total number of arenas. -.IP -The default value for the -.B M_ARENA_TEST -parameter is 2 on systems where -.I sizeof(long) -is 4; otherwise the default value is 8. -.IP -This parameter has been available since glibc 2.10 via -.BR \-\-enable\-experimental\-malloc , -and since glibc 2.15 by default. -.IP -The value of -.B M_ARENA_TEST -is not used when -.B M_ARENA_MAX -has a nonzero value. -.TP -.B M_CHECK_ACTION -Setting this parameter controls how glibc responds when various kinds -of programming errors are detected (e.g., freeing the same pointer twice). -The 3 least significant bits (2, 1, and 0) of the value assigned -to this parameter determine the glibc behavior, as follows: -.RS -.TP -Bit 0 -If this bit is set, then print a one-line message on -.I stderr -that provides details about the error. -The message starts with the string "***\ glibc detected\ ***", -followed by the program name, -the name of the memory-allocation function in which the error was detected, -a brief description of the error, -and the memory address where the error was detected. -.TP -Bit 1 -If this bit is set, then, -after printing any error message specified by bit 0, -the program is terminated by calling -.BR abort (3). -Since glibc 2.4, -if bit 0 is also set, -then, between printing the error message and aborting, -the program also prints a stack trace in the manner of -.BR backtrace (3), -and prints the process's memory mapping in the style of -.IR /proc/ pid /maps -(see -.BR proc (5)). -.TP -Bit 2 (since glibc 2.4) -This bit has an effect only if bit 0 is also set. -If this bit is set, -then the one-line message describing the error is simplified -to contain just the name of the function where the error -was detected and the brief description of the error. -.RE -.IP -The remaining bits in -.I value -are ignored. -.IP -Combining the above details, -the following numeric values are meaningful for -.BR M_CHECK_ACTION : -.RS 12 -.TP -.B 0 -Ignore error conditions; continue execution (with undefined results). -.TP -.B 1 -Print a detailed error message and continue execution. -.TP -.B 2 -Abort the program. -.TP -.B 3 -Print detailed error message, stack trace, and memory mappings, -and abort the program. -.TP -.B 5 -Print a simple error message and continue execution. -.TP -.B 7 -Print simple error message, stack trace, and memory mappings, -and abort the program. -.RE -.IP -Since glibc 2.3.4, the default value for the -.B M_CHECK_ACTION -parameter is 3. -In glibc 2.3.3 and earlier, the default value is 1. -.IP -Using a nonzero -.B M_CHECK_ACTION -value can be useful because otherwise a crash may happen much later, -and the true cause of the problem is then very hard to track down. -.TP -.B M_MMAP_MAX -.\" The following text adapted from comments in the glibc source: -This parameter specifies the maximum number of allocation requests that -may be simultaneously serviced using -.BR mmap (2). -This parameter exists because some systems have a limited number -of internal tables for use by -.BR mmap (2), -and using more than a few of them may degrade performance. -.IP -The default value is 65,536, -a value which has no special significance and -which serves only as a safeguard. -Setting this parameter to 0 disables the use of -.BR mmap (2) -for servicing large allocation requests. -.TP -.B M_MMAP_THRESHOLD -For allocations greater than or equal to the limit specified (in bytes) by -.B M_MMAP_THRESHOLD -that can't be satisfied from the free list, -the memory-allocation functions employ -.BR mmap (2) -instead of increasing the program break using -.BR sbrk (2). -.IP -Allocating memory using -.BR mmap (2) -has the significant advantage that the allocated memory blocks -can always be independently released back to the system. -(By contrast, -the heap can be trimmed only if memory is freed at the top end.) -On the other hand, there are some disadvantages to the use of -.BR mmap (2): -deallocated space is not placed on the free list -for reuse by later allocations; -memory may be wasted because -.BR mmap (2) -allocations must be page-aligned; -and the kernel must perform the expensive task of zeroing out -memory allocated via -.BR mmap (2). -Balancing these factors leads to a default setting of 128*1024 for the -.B M_MMAP_THRESHOLD -parameter. -.IP -The lower limit for this parameter is 0. -The upper limit is -.BR DEFAULT_MMAP_THRESHOLD_MAX : -512*1024 on 32-bit systems or -.I 4*1024*1024*sizeof(long) -on 64-bit systems. -.IP -.IR Note : -Nowadays, glibc uses a dynamic mmap threshold by default. -The initial value of the threshold is 128*1024, -but when blocks larger than the current threshold and less than or equal to -.B DEFAULT_MMAP_THRESHOLD_MAX -are freed, -the threshold is adjusted upward to the size of the freed block. -When dynamic mmap thresholding is in effect, -the threshold for trimming the heap is also dynamically adjusted -to be twice the dynamic mmap threshold. -Dynamic adjustment of the mmap threshold is disabled if any of the -.BR M_TRIM_THRESHOLD , -.BR M_TOP_PAD , -.BR M_MMAP_THRESHOLD , -or -.B M_MMAP_MAX -parameters is set. -.TP -.BR M_MXFAST " (since glibc 2.3)" -.\" The following text adapted from comments in the glibc sources: -Set the upper limit for memory allocation requests that are satisfied -using "fastbins". -(The measurement unit for this parameter is bytes.) -Fastbins are storage areas that hold deallocated blocks of memory -of the same size without merging adjacent free blocks. -Subsequent reallocation of blocks of the same size can be handled -very quickly by allocating from the fastbin, -although memory fragmentation and the overall memory footprint -of the program can increase. -.IP -The default value for this parameter is -.I 64*sizeof(size_t)/4 -(i.e., 64 on 32-bit architectures). -The range for this parameter is 0 to -.IR 80*sizeof(size_t)/4 . -Setting -.B M_MXFAST -to 0 disables the use of fastbins. -.TP -.BR M_PERTURB " (since glibc 2.4)" -If this parameter is set to a nonzero value, -then bytes of allocated memory (other than allocations via -.BR calloc (3)) -are initialized to the complement of the value -in the least significant byte of -.IR value , -and when allocated memory is released using -.BR free (3), -the freed bytes are set to the least significant byte of -.IR value . -This can be useful for detecting errors where programs -incorrectly rely on allocated memory being initialized to zero, -or reuse values in memory that has already been freed. -.IP -The default value for this parameter is 0. -.TP -.B M_TOP_PAD -This parameter defines the amount of padding to employ when calling -.BR sbrk (2) -to modify the program break. -(The measurement unit for this parameter is bytes.) -This parameter has an effect in the following circumstances: -.RS -.IP \[bu] 3 -When the program break is increased, then -.B M_TOP_PAD -bytes are added to the -.BR sbrk (2) -request. -.IP \[bu] -When the heap is trimmed as a consequence of calling -.BR free (3) -(see the discussion of -.BR M_TRIM_THRESHOLD ) -this much free space is preserved at the top of the heap. -.RE -.IP -In either case, -the amount of padding is always rounded to a system page boundary. -.IP -Modifying -.B M_TOP_PAD -is a trade-off between increasing the number of system calls -(when the parameter is set low) -and wasting unused memory at the top of the heap -(when the parameter is set high). -.IP -The default value for this parameter is 128*1024. -.\" DEFAULT_TOP_PAD in glibc source -.TP -.B M_TRIM_THRESHOLD -When the amount of contiguous free memory at the top of the heap -grows sufficiently large, -.BR free (3) -employs -.BR sbrk (2) -to release this memory back to the system. -(This can be useful in programs that continue to execute for -a long period after freeing a significant amount of memory.) -The -.B M_TRIM_THRESHOLD -parameter specifies the minimum size (in bytes) that -this block of memory must reach before -.BR sbrk (2) -is used to trim the heap. -.IP -The default value for this parameter is 128*1024. -Setting -.B M_TRIM_THRESHOLD -to \-1 disables trimming completely. -.IP -Modifying -.B M_TRIM_THRESHOLD -is a trade-off between increasing the number of system calls -(when the parameter is set low) -and wasting unused memory at the top of the heap -(when the parameter is set high). -.\" -.SS Environment variables -A number of environment variables can be defined -to modify some of the same parameters as are controlled by -.BR mallopt (). -Using these variables has the advantage that the source code -of the program need not be changed. -To be effective, these variables must be defined before the -first call to a memory-allocation function. -(If the same parameters are adjusted via -.BR mallopt (), -then the -.BR mallopt () -settings take precedence.) -For security reasons, -these variables are ignored in set-user-ID and set-group-ID programs. -.P -The environment variables are as follows -(note the trailing underscore at the end of the name of some variables): -.TP -.B MALLOC_ARENA_MAX -Controls the same parameter as -.BR mallopt () -.BR M_ARENA_MAX . -.TP -.B MALLOC_ARENA_TEST -Controls the same parameter as -.BR mallopt () -.BR M_ARENA_TEST . -.TP -.B MALLOC_CHECK_ -This environment variable controls the same parameter as -.BR mallopt () -.BR M_CHECK_ACTION . -If this variable is set to a nonzero value, -then a special implementation of the memory-allocation functions is used. -(This is accomplished using the -.BR malloc_hook (3) -feature.) -This implementation performs additional error checking, -but is slower -.\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower -.\" when MALLOC_CHECK_ was set. -than the standard set of memory-allocation functions. -(This implementation does not detect all possible errors; -memory leaks can still occur.) -.IP -The value assigned to this environment variable should be a single digit, -whose meaning is as described for -.BR M_CHECK_ACTION . -Any characters beyond the initial digit are ignored. -.IP -For security reasons, the effect of -.B MALLOC_CHECK_ -is disabled by default for set-user-ID and set-group-ID programs. -However, if the file -.I /etc/suid\-debug -exists (the content of the file is irrelevant), then -.B MALLOC_CHECK_ -also has an effect for set-user-ID and set-group-ID programs. -.TP -.B MALLOC_MMAP_MAX_ -Controls the same parameter as -.BR mallopt () -.BR M_MMAP_MAX . -.TP -.B MALLOC_MMAP_THRESHOLD_ -Controls the same parameter as -.BR mallopt () -.BR M_MMAP_THRESHOLD . -.TP -.B MALLOC_PERTURB_ -Controls the same parameter as -.BR mallopt () -.BR M_PERTURB . -.TP -.B MALLOC_TRIM_THRESHOLD_ -Controls the same parameter as -.BR mallopt () -.BR M_TRIM_THRESHOLD . -.TP -.B MALLOC_TOP_PAD_ -Controls the same parameter as -.BR mallopt () -.BR M_TOP_PAD . -.SH RETURN VALUE -On success, -.BR mallopt () -returns 1. -On error, it returns 0. -.SH ERRORS -On error, -.I errno -is -.I not -set. -.SH VERSIONS -A similar function exists on many System V derivatives, -but the range of values for -.I param -varies across systems. -The SVID defined options -.BR M_MXFAST , -.BR M_NLBLKS , -.BR M_GRAIN , -and -.BR M_KEEP , -but only the first of these is implemented in glibc. -.SH STANDARDS -None. -.SH HISTORY -glibc 2.0. -.SH BUGS -Specifying an invalid value for -.I param -does not generate an error. -.P -A calculation error within the glibc implementation means that -a call of the form: -.\" FIXME . This looks buggy: -.\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK) -.\" malloc requests are rounded up: -.\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK -.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12129 -.P -.in +4n -.EX -mallopt(M_MXFAST, n) -.EE -.in -.P -does not result in fastbins being employed for all allocations of size up to -.IR n . -To ensure desired results, -.I n -should be rounded up to the next multiple greater than or equal to -.IR (2k+1)*sizeof(size_t) , -where -.I k -is an integer. -.\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t) -.P -If -.BR mallopt () -is used to set -.BR M_PERTURB , -then, as expected, the bytes of allocated memory are initialized -to the complement of the byte in -.IR value , -and when that memory is freed, -the bytes of the region are initialized to the byte specified in -.IR value . -However, there is an -.RI off-by- sizeof(size_t) -error in the implementation: -.\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12140 -instead of initializing precisely the block of memory -being freed by the call -.IR free(p) , -the block starting at -.I p+sizeof(size_t) -is initialized. -.SH EXAMPLES -The program below demonstrates the use of -.BR M_CHECK_ACTION . -If the program is supplied with an (integer) command-line argument, -then that argument is used to set the -.B M_CHECK_ACTION -parameter. -The program then allocates a block of memory, -and frees it twice (an error). -.P -The following shell session shows what happens when we run this program -under glibc, with the default value for -.BR M_CHECK_ACTION : -.P -.in +4n -.EX -$ \fB./a.out\fP -main(): returned from first free() call -*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 *** -======= Backtrace: ========= -/lib/libc.so.6(+0x6c501)[0x523501] -/lib/libc.so.6(+0x6dd70)[0x524d70] -/lib/libc.so.6(cfree+0x6d)[0x527e5d] -\&./a.out[0x80485db] -/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7] -\&./a.out[0x8048471] -======= Memory map: ======== -001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1 -001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1 -[some lines omitted] -b7814000\-b7817000 rw\-p 00000000 00:00 0 -bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack] -Aborted (core dumped) -.EE -.in -.P -The following runs show the results when employing other values for -.BR M_CHECK_ACTION : -.P -.in +4n -.EX -$ \fB./a.out 1\fP # Diagnose error and continue -main(): returned from first free() call -*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 *** -main(): returned from second free() call -$ \fB./a.out 2\fP # Abort without error message -main(): returned from first free() call -Aborted (core dumped) -$ \fB./a.out 0\fP # Ignore error and continue -main(): returned from first free() call -main(): returned from second free() call -.EE -.in -.P -The next run shows how to set the same parameter using the -.B MALLOC_CHECK_ -environment variable: -.P -.in +4n -.EX -$ \fBMALLOC_CHECK_=1 ./a.out\fP -main(): returned from first free() call -*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 *** -main(): returned from second free() call -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (mallopt.c) -.EX -#include <malloc.h> -#include <stdio.h> -#include <stdlib.h> -\& -int -main(int argc, char *argv[]) -{ - char *p; -\& - if (argc > 1) { - if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) { - fprintf(stderr, "mallopt() failed"); - exit(EXIT_FAILURE); - } - } -\& - p = malloc(1000); - if (p == NULL) { - fprintf(stderr, "malloc() failed"); - exit(EXIT_FAILURE); - } -\& - free(p); - printf("%s(): returned from first free() call\en", __func__); -\& - free(p); - printf("%s(): returned from second free() call\en", __func__); -\& - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.ad l -.nh -.BR mmap (2), -.BR sbrk (2), -.BR mallinfo (3), -.BR malloc (3), -.BR malloc_hook (3), -.BR malloc_info (3), -.BR malloc_stats (3), -.BR malloc_trim (3), -.BR mcheck (3), -.BR mtrace (3), -.BR posix_memalign (3) |