man3/mallinfo.3

   1 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH MALLINFO 3  2021-03-22 "Linux man-pages (unreleased)"
   6 .SH NAME
   7 mallinfo, mallinfo2 \- obtain memory allocation information
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <malloc.h>
  14 .PP
  15 .B struct mallinfo mallinfo(void);
  16 .B struct mallinfo2 mallinfo2(void);
  17 .fi
  18 .SH DESCRIPTION
  19 These functions return a copy of a structure containing information about
  20 memory allocations performed by
  21 .BR malloc (3)
  22 and related functions.
  23 The structure returned by each function contains the same fields.
  24 However, the older function,
  25 .BR mallinfo (),
  26 is deprecated since the type used for the fields is too small (see BUGS).
  27 .PP
  28 Note that not all allocations are visible to these functions;
  29 see BUGS and consider using
  30 .BR malloc_info (3)
  31 instead.
  32 .PP
  33 The
  34 .I mallinfo2
  35 structure returned by
  36 .BR mallinfo2 ()
  37 is defined as follows:
  38 .PP
  39 .in +4n
  40 .EX
  41 struct mallinfo2 {
  42     size_t arena;     /* Non\-mmapped space allocated (bytes) */
  43     size_t ordblks;   /* Number of free chunks */
  44     size_t smblks;    /* Number of free fastbin blocks */
  45     size_t hblks;     /* Number of mmapped regions */
  46     size_t hblkhd;    /* Space allocated in mmapped regions
  47                          (bytes) */
  48     size_t usmblks;   /* See below */
  49     size_t fsmblks;   /* Space in freed fastbin blocks (bytes) */
  50     size_t uordblks;  /* Total allocated space (bytes) */
  51     size_t fordblks;  /* Total free space (bytes) */
  52     size_t keepcost;  /* Top\-most, releasable space (bytes) */
  53 };
  54 .EE
  55 .in
  56 .PP
  57 The
  58 .I mallinfo
  59 structure returned by the deprecated
  60 .BR mallinfo ()
  61 function is exactly the same, except that the fields are typed as
  62 .IR int .
  63 .PP
  64 The structure fields contain the following information:
  65 .TP 10
  66 .I arena
  67 The total amount of memory allocated by means other than
  68 .BR mmap (2)
  69 (i.e., memory allocated on the heap).
  70 This figure includes both in-use blocks and blocks on the free list.
  71 .TP
  72 .I ordblks
  73 The number of ordinary (i.e., non-fastbin) free blocks.
  74 .TP
  75 .I smblks
  76 .\" the glibc info page wrongly says this field is unused
  77 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746
  78 The number of fastbin free blocks (see
  79 .BR mallopt (3)).
  80 .TP
  81 .I hblks
  82 The number of blocks currently allocated using
  83 .BR mmap (2).
  84 (See the discussion of
  85 .B M_MMAP_THRESHOLD
  86 in
  87 .BR mallopt (3).)
  88 .TP
  89 .I hblkhd
  90 The number of bytes in blocks currently allocated using
  91 .BR mmap (2).
  92 .TP
  93 .I usmblks
  94 This field is unused, and is always 0.
  95 .\" It seems to have been zero since at least as far back as glibc 2.15
  96 Historically, it was the "highwater mark" for allocated space\(emthat is,
  97 the maximum amount of space that was ever allocated (in bytes);
  98 this field was maintained only in nonthreading environments.
  99 .TP
 100 .I fsmblks
 101 .\" the glibc info page wrongly says this field is unused
 102 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=26746
 103 The total number of bytes in fastbin free blocks.
 104 .TP
 105 .I uordblks
 106 The total number of bytes used by in-use allocations.
 107 .TP
 108 .I fordblks
 109 The total number of bytes in free blocks.
 110 .TP
 111 .I keepcost
 112 The total amount of releasable free space at the top
 113 of the heap.
 114 This is the maximum number of bytes that could ideally
 115 (i.e., ignoring page alignment restrictions, and so on) be released by
 116 .BR malloc_trim (3).
 117 .SH VERSIONS
 118 .\" mallinfo(): Available already in glibc 2.0, possibly earlier
 119 The
 120 .BR mallinfo2 ()
 121 function was added
 122 .\" commit e3960d1c57e57f33e0e846d615788f4ede73b945
 123 in glibc 2.33.
 124 .SH ATTRIBUTES
 125 For an explanation of the terms used in this section, see
 126 .BR attributes (7).
 127 .ad l
 128 .nh
 129 .TS
 130 allbox;
 131 lb lb lbx
 132 l l l.
 133 Interface       Attribute       Value
 134 T{
 135 .BR mallinfo (),
 136 .BR mallinfo2 ()
 137 T}      Thread safety   T{
 138 MT-Unsafe init const:mallopt
 139 T}
 140 .TE
 141 .hy
 142 .ad
 143 .sp 1
 144 .BR mallinfo ()/
 145 .BR mallinfo2 ()
 146 would access some global internal objects.
 147 If modify them with non-atomically,
 148 may get inconsistent results.
 149 The identifier
 150 .I mallopt
 151 in
 152 .I const:mallopt
 153 mean that
 154 .BR mallopt ()
 155 would modify the global internal objects with atomics, that make sure
 156 .BR mallinfo ()/
 157 .BR mallinfo2 ()
 158 is safe enough, others modify with non-atomically maybe not.
 159 .SH STANDARDS
 160 These functions are not specified by POSIX or the C standards.
 161 A
 162 .BR mallinfo ()
 163 function exists on many System V derivatives,
 164 and was specified in the SVID.
 165 .SH BUGS
 166 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=208
 167 .\" See the 24 Aug 2011 mail by Paul Pluzhnikov:
 168 .\"     "[patch] Fix mallinfo() to accumulate results for all arenas"
 169 .\" on libc-alpha@sourceware.org
 170 .B Information is returned for only the main memory allocation area.
 171 Allocations in other arenas are excluded.
 172 See
 173 .BR malloc_stats (3)
 174 and
 175 .BR malloc_info (3)
 176 for alternatives that include information about other arenas.
 177 .PP
 178 The fields of the
 179 .I mallinfo
 180 structure that is returned by the older
 181 .BR mallinfo ()
 182 function are typed as
 183 .IR int .
 184 However, because some internal bookkeeping values may be of type
 185 .IR long ,
 186 the reported values may wrap around zero and thus be inaccurate.
 187 .SH EXAMPLES
 188 The program below employs
 189 .BR mallinfo2 ()
 190 to retrieve memory allocation statistics before and after
 191 allocating and freeing some blocks of memory.
 192 The statistics are displayed on standard output.
 193 .PP
 194 The first two command-line arguments specify the number and size of
 195 blocks to be allocated with
 196 .BR malloc (3).
 197 .PP
 198 The remaining three arguments specify which of the allocated blocks
 199 should be freed with
 200 .BR free (3).
 201 These three arguments are optional, and specify (in order):
 202 the step size to be used in the loop that frees blocks
 203 (the default is 1, meaning free all blocks in the range);
 204 the ordinal position of the first block to be freed
 205 (default 0, meaning the first allocated block);
 206 and a number one greater than the ordinal position
 207 of the last block to be freed
 208 (default is one greater than the maximum block number).
 209 If these three arguments are omitted,
 210 then the defaults cause all allocated blocks to be freed.
 211 .PP
 212 In the following example run of the program,
 213 1000 allocations of 100 bytes are performed,
 214 and then every second allocated block is freed:
 215 .PP
 216 .in +4n
 217 .EX
 218 $ \fB./a.out 1000 100 2\fP
 219 ============== Before allocating blocks ==============
 220 Total non\-mmapped bytes (arena):       0
 221 # of free chunks (ordblks):            1
 222 # of free fastbin blocks (smblks):     0
 223 # of mapped regions (hblks):           0
 224 Bytes in mapped regions (hblkhd):      0
 225 Max. total allocated space (usmblks):  0
 226 Free bytes held in fastbins (fsmblks): 0
 227 Total allocated space (uordblks):      0
 228 Total free space (fordblks):           0
 229 Topmost releasable block (keepcost):   0
 230
 231 ============== After allocating blocks ==============
 232 Total non\-mmapped bytes (arena):       135168
 233 # of free chunks (ordblks):            1
 234 # of free fastbin blocks (smblks):     0
 235 # of mapped regions (hblks):           0
 236 Bytes in mapped regions (hblkhd):      0
 237 Max. total allocated space (usmblks):  0
 238 Free bytes held in fastbins (fsmblks): 0
 239 Total allocated space (uordblks):      104000
 240 Total free space (fordblks):           31168
 241 Topmost releasable block (keepcost):   31168
 242
 243 ============== After freeing blocks ==============
 244 Total non\-mmapped bytes (arena):       135168
 245 # of free chunks (ordblks):            501
 246 # of free fastbin blocks (smblks):     0
 247 # of mapped regions (hblks):           0
 248 Bytes in mapped regions (hblkhd):      0
 249 Max. total allocated space (usmblks):  0
 250 Free bytes held in fastbins (fsmblks): 0
 251 Total allocated space (uordblks):      52000
 252 Total free space (fordblks):           83168
 253 Topmost releasable block (keepcost):   31168
 254 .EE
 255 .in
 256 .SS Program source
 257 \&
 258 .EX
 259 #include <malloc.h>
 260 #include <stdlib.h>
 261 #include <string.h>
 262
 263 static void
 264 display_mallinfo2(void)
 265 {
 266     struct mallinfo2 mi;
 267
 268     mi = mallinfo2();
 269
 270     printf("Total non\-mmapped bytes (arena):       %zu\en", mi.arena);
 271     printf("# of free chunks (ordblks):            %zu\en", mi.ordblks);
 272     printf("# of free fastbin blocks (smblks):     %zu\en", mi.smblks);
 273     printf("# of mapped regions (hblks):           %zu\en", mi.hblks);
 274     printf("Bytes in mapped regions (hblkhd):      %zu\en", mi.hblkhd);
 275     printf("Max. total allocated space (usmblks):  %zu\en", mi.usmblks);
 276     printf("Free bytes held in fastbins (fsmblks): %zu\en", mi.fsmblks);
 277     printf("Total allocated space (uordblks):      %zu\en", mi.uordblks);
 278     printf("Total free space (fordblks):           %zu\en", mi.fordblks);
 279     printf("Topmost releasable block (keepcost):   %zu\en", mi.keepcost);
 280 }
 281
 282 int
 283 main(int argc, char *argv[])
 284 {
 285 #define MAX_ALLOCS 2000000
 286     char *alloc[MAX_ALLOCS];
 287     int numBlocks, freeBegin, freeEnd, freeStep;
 288     size_t blockSize;
 289
 290     if (argc < 3 || strcmp(argv[1], "\-\-help") == 0) {
 291         fprintf(stderr, "%s num\-blocks block\-size [free\-step "
 292                 "[start\-free [end\-free]]]\en", argv[0]);
 293         exit(EXIT_FAILURE);
 294     }
 295
 296     numBlocks = atoi(argv[1]);
 297     blockSize = atoi(argv[2]);
 298     freeStep = (argc > 3) ? atoi(argv[3]) : 1;
 299     freeBegin = (argc > 4) ? atoi(argv[4]) : 0;
 300     freeEnd = (argc > 5) ? atoi(argv[5]) : numBlocks;
 301
 302     printf("============== Before allocating blocks ==============\en");
 303     display_mallinfo2();
 304
 305     for (int j = 0; j < numBlocks; j++) {
 306         if (numBlocks >= MAX_ALLOCS) {
 307             fprintf(stderr, "Too many allocations\en");
 308             exit(EXIT_FAILURE);
 309         }
 310
 311         alloc[j] = malloc(blockSize);
 312         if (alloc[j] == NULL) {
 313             perror("malloc");
 314             exit(EXIT_FAILURE);
 315         }
 316     }
 317
 318     printf("\en============== After allocating blocks ==============\en");
 319     display_mallinfo2();
 320
 321     for (int j = freeBegin; j < freeEnd; j += freeStep)
 322         free(alloc[j]);
 323
 324     printf("\en============== After freeing blocks ==============\en");
 325     display_mallinfo2();
 326
 327     exit(EXIT_SUCCESS);
 328 }
 329 .EE
 330 .SH SEE ALSO
 331 .ad l
 332 .nh
 333 .BR mmap (2),
 334 .BR malloc (3),
 335 .BR malloc_info (3),
 336 .BR malloc_stats (3),
 337 .BR malloc_trim (3),
 338 .BR mallopt (3)