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 .P
  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 .P
  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 .SH STANDARDS
  59 GNU.
  60 .SH HISTORY
  61 glibc 2.10.
  62 .SH NOTES
  63 The memory-allocation information is provided as an XML string
  64 (rather than a C structure)
  65 because the information may change over time
  66 (according to changes in the underlying implementation).
  67 The output XML string includes a version field.
  68 .P
  69 The
  70 .BR open_memstream (3)
  71 function can be used to send the output of
  72 .BR malloc_info ()
  73 directly into a buffer in memory, rather than to a file.
  74 .P
  75 The
  76 .BR malloc_info ()
  77 function is designed to address deficiencies in
  78 .BR malloc_stats (3)
  79 and
  80 .BR mallinfo (3).
  81 .SH EXAMPLES
  82 The program below takes up to four command-line arguments,
  83 of which the first three are mandatory.
  84 The first argument specifies the number of threads that
  85 the program should create.
  86 All of the threads, including the main thread,
  87 allocate the number of blocks of memory specified by the second argument.
  88 The third argument controls the size of the blocks to be allocated.
  89 The main thread creates blocks of this size,
  90 the second thread created by the program allocates blocks of twice this size,
  91 the third thread allocates blocks of three times this size, and so on.
  92 .P
  93 The program calls
  94 .BR malloc_info ()
  95 twice to display the memory-allocation state.
  96 The first call takes place before any threads
  97 are created or memory allocated.
  98 The second call is performed after all threads have allocated memory.
  99 .P
 100 In the following example,
 101 the command-line arguments specify the creation of one additional thread,
 102 and both the main thread and the additional thread
 103 allocate 10000 blocks of memory.
 104 After the blocks of memory have been allocated,
 105 .BR malloc_info ()
 106 shows the state of two allocation arenas.
 107 .P
 108 .in +4n
 109 .EX
 110 .RB "$ " "getconf GNU_LIBC_VERSION"
 111 glibc 2.13
 112 .RB "$ " "./a.out 1 10000 100"
 113 ============ Before allocating blocks ============
 114 <malloc version="1">
 115 <heap nr="0">
 116 <sizes>
 117 </sizes>
 118 <total type="fast" count="0" size="0"/>
 119 <total type="rest" count="0" size="0"/>
 120 <system type="current" size="135168"/>
 121 <system type="max" size="135168"/>
 122 <aspace type="total" size="135168"/>
 123 <aspace type="mprotect" size="135168"/>
 124 </heap>
 125 <total type="fast" count="0" size="0"/>
 126 <total type="rest" count="0" size="0"/>
 127 <system type="current" size="135168"/>
 128 <system type="max" size="135168"/>
 129 <aspace type="total" size="135168"/>
 130 <aspace type="mprotect" size="135168"/>
 131 </malloc>
 132 \&
 133 ============ After allocating blocks ============
 134 <malloc version="1">
 135 <heap nr="0">
 136 <sizes>
 137 </sizes>
 138 <total type="fast" count="0" size="0"/>
 139 <total type="rest" count="0" size="0"/>
 140 <system type="current" size="1081344"/>
 141 <system type="max" size="1081344"/>
 142 <aspace type="total" size="1081344"/>
 143 <aspace type="mprotect" size="1081344"/>
 144 </heap>
 145 <heap nr="1">
 146 <sizes>
 147 </sizes>
 148 <total type="fast" count="0" size="0"/>
 149 <total type="rest" count="0" size="0"/>
 150 <system type="current" size="1032192"/>
 151 <system type="max" size="1032192"/>
 152 <aspace type="total" size="1032192"/>
 153 <aspace type="mprotect" size="1032192"/>
 154 </heap>
 155 <total type="fast" count="0" size="0"/>
 156 <total type="rest" count="0" size="0"/>
 157 <system type="current" size="2113536"/>
 158 <system type="max" size="2113536"/>
 159 <aspace type="total" size="2113536"/>
 160 <aspace type="mprotect" size="2113536"/>
 161 </malloc>
 162 .EE
 163 .in
 164 .SS Program source
 165 .\" SRC BEGIN (malloc_info.c)
 166 .EX
 167 #include <err.h>
 168 #include <errno.h>
 169 #include <malloc.h>
 170 #include <pthread.h>
 171 #include <stdlib.h>
 172 #include <unistd.h>
 173 \&
 174 static size_t        blockSize;
 175 static size_t        numThreads;
 176 static unsigned int  numBlocks;
 177 \&
 178 static void *
 179 thread_func(void *arg)
 180 {
 181     int tn = (int) arg;
 182 \&
 183     /* The multiplier \[aq](2 + tn)\[aq] ensures that each thread (including
 184        the main thread) allocates a different amount of memory. */
 185 \&
 186     for (unsigned int j = 0; j < numBlocks; j++)
 187         if (malloc(blockSize * (2 + tn)) == NULL)
 188             err(EXIT_FAILURE, "malloc\-thread");
 189 \&
 190     sleep(100);         /* Sleep until main thread terminates. */
 191     return NULL;
 192 }
 193 \&
 194 int
 195 main(int argc, char *argv[])
 196 {
 197     int        sleepTime;
 198     pthread_t  *thr;
 199 \&
 200     if (argc < 4) {
 201         fprintf(stderr,
 202                 "%s num\-threads num\-blocks block\-size [sleep\-time]\en",
 203                 argv[0]);
 204         exit(EXIT_FAILURE);
 205     }
 206 \&
 207     numThreads = atoi(argv[1]);
 208     numBlocks = atoi(argv[2]);
 209     blockSize = atoi(argv[3]);
 210     sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
 211 \&
 212     thr = calloc(numThreads, sizeof(*thr));
 213     if (thr == NULL)
 214         err(EXIT_FAILURE, "calloc");
 215 \&
 216     printf("============ Before allocating blocks ============\en");
 217     malloc_info(0, stdout);
 218 \&
 219     /* Create threads that allocate different amounts of memory. */
 220 \&
 221     for (size_t tn = 0; tn < numThreads; tn++) {
 222         errno = pthread_create(&thr[tn], NULL, thread_func,
 223                                (void *) tn);
 224         if (errno != 0)
 225             err(EXIT_FAILURE, "pthread_create");
 226 \&
 227         /* If we add a sleep interval after the start\-up of each
 228            thread, the threads likely won\[aq]t contend for malloc
 229            mutexes, and therefore additional arenas won\[aq]t be
 230            allocated (see malloc(3)). */
 231 \&
 232         if (sleepTime > 0)
 233             sleep(sleepTime);
 234     }
 235 \&
 236     /* The main thread also allocates some memory. */
 237 \&
 238     for (unsigned int j = 0; j < numBlocks; j++)
 239         if (malloc(blockSize) == NULL)
 240             err(EXIT_FAILURE, "malloc");
 241 \&
 242     sleep(2);           /* Give all threads a chance to
 243                            complete allocations. */
 244 \&
 245     printf("\en============ After allocating blocks ============\en");
 246     malloc_info(0, stdout);
 247 \&
 248     exit(EXIT_SUCCESS);
 249 }
 250 .EE
 251 .\" SRC END
 252 .SH SEE ALSO
 253 .BR mallinfo (3),
 254 .BR malloc (3),
 255 .BR malloc_stats (3),
 256 .BR mallopt (3),
 257 .BR open_memstream (3)