man3/malloc_info.3

   1 '\" t
   2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH malloc_info 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 malloc_info \- export malloc state to a stream
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <malloc.h>
  15 .PP
  16 .BI "int malloc_info(int " options ", FILE *" stream );
  17 .fi
  18 .SH DESCRIPTION
  19 The
  20 .BR malloc_info ()
  21 function exports an XML string that describes the current state
  22 of the memory-allocation
  23 implementation in the caller.
  24 The string is printed on the file stream
  25 .IR stream .
  26 The exported string includes information about all arenas (see
  27 .BR malloc (3)).
  28 .PP
  29 As currently implemented,
  30 .I options
  31 must be zero.
  32 .SH RETURN VALUE
  33 On success,
  34 .BR malloc_info ()
  35 returns 0.
  36 On failure, it returns \-1, and
  37 .I errno
  38 is set to indicate the error.
  39 .SH ERRORS
  40 .TP
  41 .B EINVAL
  42 .I options
  43 was nonzero.
  44 .SH ATTRIBUTES
  45 For an explanation of the terms used in this section, see
  46 .BR attributes (7).
  47 .TS
  48 allbox;
  49 lbx lb lb
  50 l l l.
  51 Interface       Attribute       Value
  52 T{
  53 .na
  54 .nh
  55 .BR malloc_info ()
  56 T}      Thread safety   MT-Safe
  57 .TE
  58 .sp 1
  59 .SH STANDARDS
  60 GNU.
  61 .SH HISTORY
  62 glibc 2.10.
  63 .SH NOTES
  64 The memory-allocation information is provided as an XML string
  65 (rather than a C structure)
  66 because the information may change over time
  67 (according to changes in the underlying implementation).
  68 The output XML string includes a version field.
  69 .PP
  70 The
  71 .BR open_memstream (3)
  72 function can be used to send the output of
  73 .BR malloc_info ()
  74 directly into a buffer in memory, rather than to a file.
  75 .PP
  76 The
  77 .BR malloc_info ()
  78 function is designed to address deficiencies in
  79 .BR malloc_stats (3)
  80 and
  81 .BR mallinfo (3).
  82 .SH EXAMPLES
  83 The program below takes up to four command-line arguments,
  84 of which the first three are mandatory.
  85 The first argument specifies the number of threads that
  86 the program should create.
  87 All of the threads, including the main thread,
  88 allocate the number of blocks of memory specified by the second argument.
  89 The third argument controls the size of the blocks to be allocated.
  90 The main thread creates blocks of this size,
  91 the second thread created by the program allocates blocks of twice this size,
  92 the third thread allocates blocks of three times this size, and so on.
  93 .PP
  94 The program calls
  95 .BR malloc_info ()
  96 twice to display the memory-allocation state.
  97 The first call takes place before any threads
  98 are created or memory allocated.
  99 The second call is performed after all threads have allocated memory.
 100 .PP
 101 In the following example,
 102 the command-line arguments specify the creation of one additional thread,
 103 and both the main thread and the additional thread
 104 allocate 10000 blocks of memory.
 105 After the blocks of memory have been allocated,
 106 .BR malloc_info ()
 107 shows the state of two allocation arenas.
 108 .PP
 109 .in +4n
 110 .EX
 111 .RB "$ " "getconf GNU_LIBC_VERSION"
 112 glibc 2.13
 113 .RB "$ " "./a.out 1 10000 100"
 114 ============ Before allocating blocks ============
 115 <malloc version="1">
 116 <heap nr="0">
 117 <sizes>
 118 </sizes>
 119 <total type="fast" count="0" size="0"/>
 120 <total type="rest" count="0" size="0"/>
 121 <system type="current" size="135168"/>
 122 <system type="max" size="135168"/>
 123 <aspace type="total" size="135168"/>
 124 <aspace type="mprotect" size="135168"/>
 125 </heap>
 126 <total type="fast" count="0" size="0"/>
 127 <total type="rest" count="0" size="0"/>
 128 <system type="current" size="135168"/>
 129 <system type="max" size="135168"/>
 130 <aspace type="total" size="135168"/>
 131 <aspace type="mprotect" size="135168"/>
 132 </malloc>
 133 \&
 134 ============ After allocating blocks ============
 135 <malloc version="1">
 136 <heap nr="0">
 137 <sizes>
 138 </sizes>
 139 <total type="fast" count="0" size="0"/>
 140 <total type="rest" count="0" size="0"/>
 141 <system type="current" size="1081344"/>
 142 <system type="max" size="1081344"/>
 143 <aspace type="total" size="1081344"/>
 144 <aspace type="mprotect" size="1081344"/>
 145 </heap>
 146 <heap nr="1">
 147 <sizes>
 148 </sizes>
 149 <total type="fast" count="0" size="0"/>
 150 <total type="rest" count="0" size="0"/>
 151 <system type="current" size="1032192"/>
 152 <system type="max" size="1032192"/>
 153 <aspace type="total" size="1032192"/>
 154 <aspace type="mprotect" size="1032192"/>
 155 </heap>
 156 <total type="fast" count="0" size="0"/>
 157 <total type="rest" count="0" size="0"/>
 158 <system type="current" size="2113536"/>
 159 <system type="max" size="2113536"/>
 160 <aspace type="total" size="2113536"/>
 161 <aspace type="mprotect" size="2113536"/>
 162 </malloc>
 163 .EE
 164 .in
 165 .SS Program source
 166 .\" SRC BEGIN (malloc_info.c)
 167 .EX
 168 #include <err.h>
 169 #include <errno.h>
 170 #include <malloc.h>
 171 #include <pthread.h>
 172 #include <stdlib.h>
 173 #include <unistd.h>
 174 \&
 175 static size_t        blockSize;
 176 static size_t        numThreads;
 177 static unsigned int  numBlocks;
 178 \&
 179 static void *
 180 thread_func(void *arg)
 181 {
 182     int tn = (int) arg;
 183 \&
 184     /* The multiplier \[aq](2 + tn)\[aq] ensures that each thread (including
 185        the main thread) allocates a different amount of memory. */
 186 \&
 187     for (unsigned int j = 0; j < numBlocks; j++)
 188         if (malloc(blockSize * (2 + tn)) == NULL)
 189             err(EXIT_FAILURE, "malloc\-thread");
 190 \&
 191     sleep(100);         /* Sleep until main thread terminates. */
 192     return NULL;
 193 }
 194 \&
 195 int
 196 main(int argc, char *argv[])
 197 {
 198     int        sleepTime;
 199     pthread_t  *thr;
 200 \&
 201     if (argc < 4) {
 202         fprintf(stderr,
 203                 "%s num\-threads num\-blocks block\-size [sleep\-time]\en",
 204                 argv[0]);
 205         exit(EXIT_FAILURE);
 206     }
 207 \&
 208     numThreads = atoi(argv[1]);
 209     numBlocks = atoi(argv[2]);
 210     blockSize = atoi(argv[3]);
 211     sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
 212 \&
 213     thr = calloc(numThreads, sizeof(*thr));
 214     if (thr == NULL)
 215         err(EXIT_FAILURE, "calloc");
 216 \&
 217     printf("============ Before allocating blocks ============\en");
 218     malloc_info(0, stdout);
 219 \&
 220     /* Create threads that allocate different amounts of memory. */
 221 \&
 222     for (size_t tn = 0; tn < numThreads; tn++) {
 223         errno = pthread_create(&thr[tn], NULL, thread_func,
 224                                (void *) tn);
 225         if (errno != 0)
 226             err(EXIT_FAILURE, "pthread_create");
 227 \&
 228         /* If we add a sleep interval after the start\-up of each
 229            thread, the threads likely won\[aq]t contend for malloc
 230            mutexes, and therefore additional arenas won\[aq]t be
 231            allocated (see malloc(3)). */
 232 \&
 233         if (sleepTime > 0)
 234             sleep(sleepTime);
 235     }
 236 \&
 237     /* The main thread also allocates some memory. */
 238 \&
 239     for (unsigned int j = 0; j < numBlocks; j++)
 240         if (malloc(blockSize) == NULL)
 241             err(EXIT_FAILURE, "malloc");
 242 \&
 243     sleep(2);           /* Give all threads a chance to
 244                            complete allocations. */
 245 \&
 246     printf("\en============ After allocating blocks ============\en");
 247     malloc_info(0, stdout);
 248 \&
 249     exit(EXIT_SUCCESS);
 250 }
 251 .EE
 252 .\" SRC END
 253 .SH SEE ALSO
 254 .BR mallinfo (3),
 255 .BR malloc (3),
 256 .BR malloc_stats (3),
 257 .BR mallopt (3),
 258 .BR open_memstream (3)