summaryrefslogtreecommitdiffstats
path: root/man3/mallopt.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/mallopt.3')
-rw-r--r--man3/mallopt.3619
1 files changed, 0 insertions, 619 deletions
diff --git a/man3/mallopt.3 b/man3/mallopt.3
deleted file mode 100644
index 6922b0f..0000000
--- 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 2024-02-26 "Linux man-pages 6.7"
-.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)