diff options
author | Paul Eggert <eggert@cs.ucla.edu> | 2021-04-11 19:06:00 -0700 |
---|---|---|
committer | Paul Eggert <eggert@cs.ucla.edu> | 2021-04-13 12:17:56 -0700 |
commit | bdc674d97ba8b59e22b1f45fa1a37862764fcc75 (patch) | |
tree | 66b8438f974eb3910663d1a0f047f256de376f50 /manual/tunables.texi | |
parent | cedbf6d5f3f70ca911176de87d6e453eeab4b7a1 (diff) | |
download | glibc-bdc674d97ba8b59e22b1f45fa1a37862764fcc75.zip glibc-bdc674d97ba8b59e22b1f45fa1a37862764fcc75.tar.gz glibc-bdc674d97ba8b59e22b1f45fa1a37862764fcc75.tar.bz2 |
Improve documentation for malloc etc. (BZ#27719)
Cover key corner cases (e.g., whether errno is set) that are well
settled in glibc, fix some examples to avoid integer overflow, and
update some other dated examples (code needed for K&R C, e.g.).
* manual/charset.texi (Non-reentrant String Conversion):
* manual/filesys.texi (Symbolic Links):
* manual/memory.texi (Allocating Cleared Space):
* manual/socket.texi (Host Names):
* manual/string.texi (Concatenating Strings):
* manual/users.texi (Setting Groups):
Use reallocarray instead of realloc, to avoid integer overflow issues.
* manual/filesys.texi (Scanning Directory Content):
* manual/memory.texi (The GNU Allocator, Hooks for Malloc):
* manual/tunables.texi:
Use code font for 'malloc' instead of roman font.
(Symbolic Links): Don't assume readlink return value fits in 'int'.
* manual/memory.texi (Memory Allocation and C, Basic Allocation)
(Malloc Examples, Alloca Example):
* manual/stdio.texi (Formatted Output Functions):
* manual/string.texi (Concatenating Strings, Collation Functions):
Omit pointer casts that are needed only in ancient K&R C.
* manual/memory.texi (Basic Allocation):
Say that malloc sets errno on failure.
Say "convert" rather than "cast", since casts are no longer needed.
* manual/memory.texi (Basic Allocation):
* manual/string.texi (Concatenating Strings):
In examples, use C99 declarations after statements for brevity.
* manual/memory.texi (Malloc Examples): Add portability notes for
malloc (0), errno setting, and PTRDIFF_MAX.
(Changing Block Size): Say that realloc (p, 0) acts like
(p ? (free (p), NULL) : malloc (0)).
Add xreallocarray example, since other examples can use it.
Add portability notes for realloc (0, 0), realloc (p, 0),
PTRDIFF_MAX, and improve notes for reallocating to the same size.
(Allocating Cleared Space): Reword now-confusing discussion
about replacement, and xref "Replacing malloc".
* manual/stdio.texi (Formatted Output Functions):
Don't assume message size fits in 'int'.
* manual/string.texi (Concatenating Strings):
Fix undefined behavior involving arithmetic on a freed pointer.
Diffstat (limited to 'manual/tunables.texi')
-rw-r--r-- | manual/tunables.texi | 14 |
1 files changed, 8 insertions, 6 deletions
diff --git a/manual/tunables.texi b/manual/tunables.texi index 1b746c0..6de647b 100644 --- a/manual/tunables.texi +++ b/manual/tunables.texi @@ -10,7 +10,8 @@ their workload. These are implemented as a set of switches that may be modified in different ways. The current default method to do this is via the @env{GLIBC_TUNABLES} environment variable by setting it to a string of colon-separated @var{name}=@var{value} pairs. For example, the following -example enables malloc checking and sets the malloc trim threshold to 128 +example enables @code{malloc} checking and sets the @code{malloc} +trim threshold to 128 bytes: @example @@ -115,7 +116,7 @@ This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is identical in features. Setting this tunable to a non-zero value enables a special (less -efficient) memory allocator for the malloc family of functions that is +efficient) memory allocator for the @code{malloc} family of functions that is designed to be tolerant against simple errors such as double calls of free with the same argument, or overruns of a single byte (off-by-one bugs). Not all such errors can be protected against, however, and memory @@ -149,7 +150,7 @@ identical in features. If set to a non-zero value, memory blocks are initialized with values depending on some low order bits of this tunable when they are allocated (except when -allocated by calloc) and freed. This can be used to debug the use of +allocated by @code{calloc}) and freed. This can be used to debug the use of uninitialized or freed heap memory. Note that this option does not guarantee that the freed block will have any specific values. It only guarantees that the content the block had before it was freed will be overwritten. @@ -256,13 +257,13 @@ is no limit. @end deftp @deftp Tunable glibc.malloc.mxfast -One of the optimizations malloc uses is to maintain a series of ``fast +One of the optimizations @code{malloc} uses is to maintain a series of ``fast bins'' that hold chunks up to a specific size. The default and maximum size which may be held this way is 80 bytes on 32-bit systems or 160 bytes on 64-bit systems. Applications which value size over speed may choose to reduce the size of requests which are serviced from fast bins with this tunable. Note that the value specified -includes malloc's internal overhead, which is normally the size of one +includes @code{malloc}'s internal overhead, which is normally the size of one pointer, so add 4 on 32-bit systems or 8 on 64-bit systems to the size passed to @code{malloc} for the largest bin size to enable. @end deftp @@ -543,7 +544,8 @@ all other systems. This tunable takes a value between 0 and 255 and acts as a bitmask that enables various capabilities. -Bit 0 (the least significant bit) causes the malloc subsystem to allocate +Bit 0 (the least significant bit) causes the @code{malloc} +subsystem to allocate tagged memory, with each allocation being assigned a random tag. Bit 1 enables precise faulting mode for tag violations on systems that |