Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 257 insertions, 0 deletions

diff --git a/man/man3/malloc_info.3 b/man/man3/malloc_info.3
new file mode 100644
index 0000000..086b3b2
--- /dev/null
+++ b/man/man3/malloc_info.3
@@ -0,0 +1,257 @@
+'\" t
+.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH malloc_info 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+malloc_info \- export malloc state to a stream
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <malloc.h>
+.P
+.BI "int malloc_info(int " options ", FILE *" stream );
+.fi
+.SH DESCRIPTION
+The
+.BR malloc_info ()
+function exports an XML string that describes the current state
+of the memory-allocation
+implementation in the caller.
+The string is printed on the file stream
+.IR stream .
+The exported string includes information about all arenas (see
+.BR malloc (3)).
+.P
+As currently implemented,
+.I options
+must be zero.
+.SH RETURN VALUE
+On success,
+.BR malloc_info ()
+returns 0.
+On failure, it returns \-1, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+.I options
+was nonzero.
+.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_info ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+GNU.
+.SH HISTORY
+glibc 2.10.
+.SH NOTES
+The memory-allocation information is provided as an XML string
+(rather than a C structure)
+because the information may change over time
+(according to changes in the underlying implementation).
+The output XML string includes a version field.
+.P
+The
+.BR open_memstream (3)
+function can be used to send the output of
+.BR malloc_info ()
+directly into a buffer in memory, rather than to a file.
+.P
+The
+.BR malloc_info ()
+function is designed to address deficiencies in
+.BR malloc_stats (3)
+and
+.BR mallinfo (3).
+.SH EXAMPLES
+The program below takes up to four command-line arguments,
+of which the first three are mandatory.
+The first argument specifies the number of threads that
+the program should create.
+All of the threads, including the main thread,
+allocate the number of blocks of memory specified by the second argument.
+The third argument controls the size of the blocks to be allocated.
+The main thread creates blocks of this size,
+the second thread created by the program allocates blocks of twice this size,
+the third thread allocates blocks of three times this size, and so on.
+.P
+The program calls
+.BR malloc_info ()
+twice to display the memory-allocation state.
+The first call takes place before any threads
+are created or memory allocated.
+The second call is performed after all threads have allocated memory.
+.P
+In the following example,
+the command-line arguments specify the creation of one additional thread,
+and both the main thread and the additional thread
+allocate 10000 blocks of memory.
+After the blocks of memory have been allocated,
+.BR malloc_info ()
+shows the state of two allocation arenas.
+.P
+.in +4n
+.EX
+.RB "$ " "getconf GNU_LIBC_VERSION"
+glibc 2.13
+.RB "$ " "./a.out 1 10000 100"
+============ Before allocating blocks ============
+<malloc version="1">
+<heap nr="0">
+<sizes>
+</sizes>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="135168"/>
+<system type="max" size="135168"/>
+<aspace type="total" size="135168"/>
+<aspace type="mprotect" size="135168"/>
+</heap>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="135168"/>
+<system type="max" size="135168"/>
+<aspace type="total" size="135168"/>
+<aspace type="mprotect" size="135168"/>
+</malloc>
+\&
+============ After allocating blocks ============
+<malloc version="1">
+<heap nr="0">
+<sizes>
+</sizes>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="1081344"/>
+<system type="max" size="1081344"/>
+<aspace type="total" size="1081344"/>
+<aspace type="mprotect" size="1081344"/>
+</heap>
+<heap nr="1">
+<sizes>
+</sizes>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="1032192"/>
+<system type="max" size="1032192"/>
+<aspace type="total" size="1032192"/>
+<aspace type="mprotect" size="1032192"/>
+</heap>
+<total type="fast" count="0" size="0"/>
+<total type="rest" count="0" size="0"/>
+<system type="current" size="2113536"/>
+<system type="max" size="2113536"/>
+<aspace type="total" size="2113536"/>
+<aspace type="mprotect" size="2113536"/>
+</malloc>
+.EE
+.in
+.SS Program source
+.\" SRC BEGIN (malloc_info.c)
+.EX
+#include <err.h>
+#include <errno.h>
+#include <malloc.h>
+#include <pthread.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+static size_t        blockSize;
+static size_t        numThreads;
+static unsigned int  numBlocks;
+\&
+static void *
+thread_func(void *arg)
+{
+    int tn = (int) arg;
+\&
+    /* The multiplier \[aq](2 + tn)\[aq] ensures that each thread (including
+       the main thread) allocates a different amount of memory. */
+\&
+    for (unsigned int j = 0; j < numBlocks; j++)
+        if (malloc(blockSize * (2 + tn)) == NULL)
+            err(EXIT_FAILURE, "malloc\-thread");
+\&
+    sleep(100);         /* Sleep until main thread terminates. */
+    return NULL;
+}
+\&
+int
+main(int argc, char *argv[])
+{
+    int        sleepTime;
+    pthread_t  *thr;
+\&
+    if (argc < 4) {
+        fprintf(stderr,
+                "%s num\-threads num\-blocks block\-size [sleep\-time]\en",
+                argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    numThreads = atoi(argv[1]);
+    numBlocks = atoi(argv[2]);
+    blockSize = atoi(argv[3]);
+    sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
+\&
+    thr = calloc(numThreads, sizeof(*thr));
+    if (thr == NULL)
+        err(EXIT_FAILURE, "calloc");
+\&
+    printf("============ Before allocating blocks ============\en");
+    malloc_info(0, stdout);
+\&
+    /* Create threads that allocate different amounts of memory. */
+\&
+    for (size_t tn = 0; tn < numThreads; tn++) {
+        errno = pthread_create(&thr[tn], NULL, thread_func,
+                               (void *) tn);
+        if (errno != 0)
+            err(EXIT_FAILURE, "pthread_create");
+\&
+        /* If we add a sleep interval after the start\-up of each
+           thread, the threads likely won\[aq]t contend for malloc
+           mutexes, and therefore additional arenas won\[aq]t be
+           allocated (see malloc(3)). */
+\&
+        if (sleepTime > 0)
+            sleep(sleepTime);
+    }
+\&
+    /* The main thread also allocates some memory. */
+\&
+    for (unsigned int j = 0; j < numBlocks; j++)
+        if (malloc(blockSize) == NULL)
+            err(EXIT_FAILURE, "malloc");
+\&
+    sleep(2);           /* Give all threads a chance to
+                           complete allocations. */
+\&
+    printf("\en============ After allocating blocks ============\en");
+    malloc_info(0, stdout);
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR mallinfo (3),
+.BR malloc (3),
+.BR malloc_stats (3),
+.BR mallopt (3),
+.BR open_memstream (3)